5

I'm wondering if the Javadoc is using on real projects, what your experience says about it?

  • 1
    What's your definition of "real"? – S.Lott Jan 12 '11 at 20:53
  • It is used to such extent, that often javadoc generated html is being released as THE documentation for a project (this is not a good thing if you have any doubts) – Mchl Jan 12 '11 at 21:14
  • Its used for Java. Is that real enough for you? – alternative Apr 27 '11 at 0:55
  • I don't javadoc my make believe projects anymore -- only the real ones. – Steven Benitez Apr 27 '11 at 1:58
5

I use it all the time. It is useful to me because it displays in my IDE as I type '.' for a method call, or when I hover over a call or class. It is much easier and faster than ctrl-clicking on an element and reading the source code to determine what in the world a call does. In it's intended role as an API documentation tool, it shines.

I don't usually use the generated web documentation while coding; however, if I'm trying to get an overview of a project (hierarchies, scopes, etc) I may generate it.

I javadoc all public members, and encourage you to do the same. Just keep in mind that the fact that documentation is there does not mean it's good. That's up to you.

2

JavaDoc is routinely used but:

1) Not always complete

2) Often not kept up to date with the code

3) Even when present, not always read.

The last is a very serious issue: If something is not obvious from the signature (e.g., a surprise, assumption, limitation, etc.), documenting it is not sufficient because it is very likely that it will not be read. (See my discussion of this problem in (related SO question))

0

I found it fun but not real useful for normal code. If I were creating code to be shared I'd generate the javadocs.

0

Javadocs are only as good as the comments their built from; if the comments aren't there, or updated, the javadoc brings little that auto-completion won't.

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service, privacy policy and cookie policy

Not the answer you're looking for? Browse other questions tagged or ask your own question.