Relevance of HTML Javadoc

classic Classic list List threaded Threaded
3 messages Options
Reply | Threaded
Open this post in threaded view
|

Relevance of HTML Javadoc

Sebastian Kürten
Hi,

I have seen that there are several improvements to Javadoc schedulded
for the next release of Java. I'm doing research on the relevance of
the HTML documentation and would appreciate your input.

Nowadays Javadoc is somehow integrated into most IDEs. For example when
I hover the mouse over a method in the source code in Eclipse, it will
automatically display the Javadoc in a small window. I am looking for
reasons why people are still using the HTML Javadoc in the browser.

I am personally using Javadoc in the browser most of the time and I
am using the IDE integration only for quick lookups. If I want to get an
overview of a class or a whole library I open the Javadoc in the
browser. I think one reason for this is, that I just find it more
convenient to read in the browser, also because of the browser's search
functionality within the page. Other reasons I could find so far:

* If I am evaluating whether to use a library in a project, I may not
  be directly able to access the docs through the IDE. It is then
  easier to just go the Javadoc in the browser.

* The device I'm viewing the docs on may actually be a different one
  than the workstation where I am coding, hence the IDE may not be
  available at all.

* Often the doc references other online material which is then easily
  accessed using the browser.

I would be very interested in your opinion on these matters. Do you
think many / the mayority of programmers are still using Javadoc in the
browser? What are the reasons for that, maybe I am missing some obvious
points?

Thanks for your feedback!
Sebastian
Reply | Threaded
Open this post in threaded view
|

Re: Relevance of HTML Javadoc

Jonathan Gibbons
Sebastian,

I think you've already hit the high points.

-- Jon

On 03/20/2016 04:23 AM, Sebastian Kürten wrote:

> Hi,
>
> I have seen that there are several improvements to Javadoc schedulded
> for the next release of Java. I'm doing research on the relevance of
> the HTML documentation and would appreciate your input.
>
> Nowadays Javadoc is somehow integrated into most IDEs. For example when
> I hover the mouse over a method in the source code in Eclipse, it will
> automatically display the Javadoc in a small window. I am looking for
> reasons why people are still using the HTML Javadoc in the browser.
>
> I am personally using Javadoc in the browser most of the time and I
> am using the IDE integration only for quick lookups. If I want to get an
> overview of a class or a whole library I open the Javadoc in the
> browser. I think one reason for this is, that I just find it more
> convenient to read in the browser, also because of the browser's search
> functionality within the page. Other reasons I could find so far:
>
> * If I am evaluating whether to use a library in a project, I may not
>    be directly able to access the docs through the IDE. It is then
>    easier to just go the Javadoc in the browser.
>
> * The device I'm viewing the docs on may actually be a different one
>    than the workstation where I am coding, hence the IDE may not be
>    available at all.
>
> * Often the doc references other online material which is then easily
>    accessed using the browser.
>
> I would be very interested in your opinion on these matters. Do you
> think many / the mayority of programmers are still using Javadoc in the
> browser? What are the reasons for that, maybe I am missing some obvious
> points?
>
> Thanks for your feedback!
> Sebastian

Reply | Threaded
Open this post in threaded view
|

Re: Relevance of HTML Javadoc

Martin Desruisseaux
In reply to this post by Sebastian Kürten

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