Take the 2-minute tour ×
Programmers Stack Exchange is a question and answer site for professional programmers interested in conceptual questions about software development. It's 100% free, no registration required.

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

share|improve this question
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
add comment

5 Answers

up vote 5 down vote accepted

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.

share|improve this answer
add comment

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

share|improve this answer
add comment

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))

share|improve this answer
add comment

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.

share|improve this answer
add comment

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))

share|improve this answer
add comment

Your Answer

 
discard

By posting your answer, you agree to the privacy policy and terms of service.

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