JaroslavTulach at 15:17, 30 December 2015 - 2015-12-30 15:17:28

←Older revision Revision as of 15:17, 30 December 2015
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].

JaroslavTulach: /* Classes aren't Entry Points */ - 2015-12-30 15:13:15

Classes aren't Entry Points

←Older revision Revision as of 15:13, 30 December 2015
Line 9: Line 9:
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.
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.
+
Always write an overview and include [[usecase]]s in it. Only then navigate user to the actual [[Javadoc]] of your methods.

JaroslavTulach at 15:12, 30 December 2015 - 2015-12-30 15:12:54

←Older revision Revision as of 15:12, 30 December 2015
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.

JaroslavTulach at 15:08, 30 December 2015 - 2015-12-30 15:08:13

←Older revision Revision as of 15:08, 30 December 2015
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 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.

JaroslavTulach at 15:07, 30 December 2015 - 2015-12-30 15:07:33

←Older revision Revision as of 15:07, 30 December 2015
Line 1: Line 1:
-
#REDIRECT [[wikipedia::javadoc]]
+
[[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 exams.

JaroslavTulach: Redirecting to wikipedia:javadoc - 2009-03-27 20:31:59

Redirecting to wikipedia:javadoc

New page

#REDIRECT [[wikipedia::javadoc]]