Javadoc
From APIDesign
| (2 intermediate revisions not shown.) | |||
| Line 1: | Line 1: | ||
[[wikipedia::javadoc|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. | [[wikipedia::javadoc|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 [[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.
Follow
