'. '

Javadoc

From APIDesign

(Difference between revisions)
Jump to: navigation, search
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.

Revision as of 15:12, 30 December 2015

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.

Personal tools
buy