Relevance of HTML Javadoc

[Martin Desruisseaux]

Hello Sebastian

I would add the following points:

  * I find online javadoc more convenient for following links, then come
    back, etc.
  * Can open links in separated tab.
  * Not all content is visible in the IDE (e.g. MathML, content of
    custom taglet).
  * Better rendering of SLD within the browser, which sometime make the
    documentation easier to read (especially tables).
  * I didn't found an easy way to show package-javadoc in the IDE (maybe
    I didn't searched hard enough).

I would also add an observation. I do not claim that it a general
tendency; just something that I occasionally observed. Among the
developers that I have meet, I noticed that those who do not bother to
open the javadoc in a browser... often do not bother to read javadoc at
all, even when provided by the IDE. Some of them just rely on the method
signature (real example: "I need to parse a String as an integer. Ah!
auto-completion on java.lang.Integer gives me a "getInteger" method
which expects a String and returns an integer - it must be what I'm
looking for" - and he used that method in his code without reading the
documentation).

    Martin


-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.openjdk.java.net/pipermail/javadoc-dev/attachments/20160321/d623a609/attachment.html>