'. '

Javadoc

From APIDesign

(Difference between revisions)
Jump to: navigation, search
(Classes aren't Entry Points)
Current revision (15:17, 30 December 2015) (edit) (undo)
 
Line 10: Line 10:
Always write an overview and include [[usecase]]s in it. Only then navigate user to the actual [[Javadoc]] of your methods.
Always write an overview and include [[usecase]]s in it. Only then navigate user to the actual [[Javadoc]] of your methods.
 +
 +
== Code Samples ==
 +
 +
Each [[Javadoc]] should be spiced with code samples. However, often the code samples are out of date, or incorrect. That is indeed bad.
 +
 +
To generate ''always correct'', ''colorized'' code snippets, use [https://github.com/jtulach/codesnippet4javadoc Codesnippet Javadoc Doclet].

Current revision

Javadoc is one of the best inventions of Java. When we were working on the Xelfi student project (which later evolved to NetBeans), we needed not just a working IDE, but also some documentation. Java was the first language that allowed one to generate documentation from the code. So we did it - we generated hundred of pages of Javadoc. Most of the methods had no comments, but as the Javadoc tool wasn't widely known at that time, everybody was impressed and we passed the final Xelfi project exams.

Not Every Package Deserves Javadoc

As generating Javadoc is so easy in Java, many projects generate it for all their classes (just like we did in case of Xelfi). However, that is wrong. Not every package, not every class in your project is intended as an API - there are often some implementation packages. Those should be left out from the Javadoc.

Classes aren't Entry Points

By default Javadoc doesn't provide an overview and many project leave it as such. That is wrong, the last thing user of an API want is to look at tens or hundreds of classes and trying to guess which one is the most important one.

Always write an overview and include usecases in it. Only then navigate user to the actual Javadoc of your methods.

Code Samples

Each Javadoc should be spiced with code samples. However, often the code samples are out of date, or incorrect. That is indeed bad.

To generate always correct, colorized code snippets, use Codesnippet Javadoc Doclet.

Personal tools