http://wiki.apidesign.org/index.php?action=history&feed=atom&title=Javadoc 2026-04-11T00:13:41Z Revision history for this page on the wiki MediaWiki 1.12.0rc1 http://wiki.apidesign.org/index.php?title=Javadoc&diff=8672&oldid=prev 2015-12-30T15:17:28Z

<p></p> <table style="background-color: white; color:black;"> <col class='diff-marker' /> <col class='diff-content' /> <col class='diff-marker' /> <col class='diff-content' /> <tr> <td colspan='2' style="background-color: white; color:black;">←Older revision</td> <td colspan='2' style="background-color: white; color:black;">Revision as of 15:17, 30 December 2015</td> </tr> <tr><td colspan="2" class="diff-lineno">Line 10:</td> <td colspan="2" class="diff-lineno">Line 10:</td></tr> <tr><td class='diff-marker'> </td><td style="background: #eee; color:black; font-size: smaller;"></td><td class='diff-marker'> </td><td style="background: #eee; color:black; font-size: smaller;"></td></tr> <tr><td class='diff-marker'> </td><td style="background: #eee; color:black; font-size: smaller;"><div>Always write an overview and include [[usecase]]s in it. Only then navigate user to the actual [[Javadoc]] of your methods.</div></td><td class='diff-marker'> </td><td style="background: #eee; color:black; font-size: smaller;"><div>Always write an overview and include [[usecase]]s in it. Only then navigate user to the actual [[Javadoc]] of your methods.</div></td></tr> <tr><td colspan="2">&nbsp;</td><td class='diff-marker'>+</td><td style="background: #cfc; color:black; font-size: smaller;"><div><ins style="color: red; font-weight: bold; text-decoration: none;"></ins></div></td></tr> <tr><td colspan="2">&nbsp;</td><td class='diff-marker'>+</td><td style="background: #cfc; color:black; font-size: smaller;"><div><ins style="color: red; font-weight: bold; text-decoration: none;">== Code Samples ==</ins></div></td></tr> <tr><td colspan="2">&nbsp;</td><td class='diff-marker'>+</td><td style="background: #cfc; color:black; font-size: smaller;"><div><ins style="color: red; font-weight: bold; text-decoration: none;"></ins></div></td></tr> <tr><td colspan="2">&nbsp;</td><td class='diff-marker'>+</td><td style="background: #cfc; color:black; font-size: smaller;"><div><ins style="color: red; font-weight: bold; text-decoration: none;">Each [[Javadoc]] should be spiced with code samples. However, often the code samples are out of date, or incorrect. That is indeed bad.</ins></div></td></tr> <tr><td colspan="2">&nbsp;</td><td class='diff-marker'>+</td><td style="background: #cfc; color:black; font-size: smaller;"><div><ins style="color: red; font-weight: bold; text-decoration: none;"></ins></div></td></tr> <tr><td colspan="2">&nbsp;</td><td class='diff-marker'>+</td><td style="background: #cfc; color:black; font-size: smaller;"><div><ins style="color: red; font-weight: bold; text-decoration: none;">To generate ''always correct'', ''colorized'' code snippets, use [https://github.com/jtulach/codesnippet4javadoc Codesnippet Javadoc Doclet].</ins></div></td></tr> </table>

JaroslavTulach http://wiki.apidesign.org/index.php?title=Javadoc&diff=8670&oldid=prev 2015-12-30T15:13:15Z

<p><span class="autocomment">Classes aren't Entry Points</span></p> <table style="background-color: white; color:black;"> <col class='diff-marker' /> <col class='diff-content' /> <col class='diff-marker' /> <col class='diff-content' /> <tr> <td colspan='2' style="background-color: white; color:black;">←Older revision</td> <td colspan='2' style="background-color: white; color:black;">Revision as of 15:13, 30 December 2015</td> </tr> <tr><td colspan="2" class="diff-lineno">Line 9:</td> <td colspan="2" class="diff-lineno">Line 9:</td></tr> <tr><td class='diff-marker'> </td><td style="background: #eee; color:black; font-size: smaller;"><div>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.</div></td><td class='diff-marker'> </td><td style="background: #eee; color:black; font-size: smaller;"><div>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.</div></td></tr> <tr><td class='diff-marker'> </td><td style="background: #eee; color:black; font-size: smaller;"></td><td class='diff-marker'> </td><td style="background: #eee; color:black; font-size: smaller;"></td></tr> <tr><td class='diff-marker'>-</td><td style="background: #ffa; color:black; font-size: smaller;"><div>Always write an overview and include [[<del style="color: red; font-weight: bold; text-decoration: none;">UseCase</del>]]s in it. Only then navigate user to the actual [[Javadoc]] of your methods.</div></td><td class='diff-marker'>+</td><td style="background: #cfc; color:black; font-size: smaller;"><div>Always write an overview and include [[<ins style="color: red; font-weight: bold; text-decoration: none;">usecase</ins>]]s in it. Only then navigate user to the actual [[Javadoc]] of your methods.</div></td></tr> </table>

JaroslavTulach http://wiki.apidesign.org/index.php?title=Javadoc&diff=8669&oldid=prev 2015-12-30T15:12:54Z

<p></p> <table style="background-color: white; color:black;"> <col class='diff-marker' /> <col class='diff-content' /> <col class='diff-marker' /> <col class='diff-content' /> <tr> <td colspan='2' style="background-color: white; color:black;">←Older revision</td> <td colspan='2' style="background-color: white; color:black;">Revision as of 15:12, 30 December 2015</td> </tr> <tr><td colspan="2" class="diff-lineno">Line 1:</td> <td colspan="2" class="diff-lineno">Line 1:</td></tr> <tr><td class='diff-marker'> </td><td style="background: #eee; color:black; font-size: smaller;"><div>[[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.</div></td><td class='diff-marker'> </td><td style="background: #eee; color:black; font-size: smaller;"><div>[[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.</div></td></tr> <tr><td colspan="2">&nbsp;</td><td class='diff-marker'>+</td><td style="background: #cfc; color:black; font-size: smaller;"><div><ins style="color: red; font-weight: bold; text-decoration: none;"></ins></div></td></tr> <tr><td colspan="2">&nbsp;</td><td class='diff-marker'>+</td><td style="background: #cfc; color:black; font-size: smaller;"><div><ins style="color: red; font-weight: bold; text-decoration: none;">== Not Every Package Deserves [[Javadoc]] ==</ins></div></td></tr> <tr><td colspan="2">&nbsp;</td><td class='diff-marker'>+</td><td style="background: #cfc; color:black; font-size: smaller;"><div><ins style="color: red; font-weight: bold; text-decoration: none;"></ins></div></td></tr> <tr><td colspan="2">&nbsp;</td><td class='diff-marker'>+</td><td style="background: #cfc; color:black; font-size: smaller;"><div><ins style="color: red; font-weight: bold; text-decoration: none;">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]].</ins></div></td></tr> <tr><td colspan="2">&nbsp;</td><td class='diff-marker'>+</td><td style="background: #cfc; color:black; font-size: smaller;"><div><ins style="color: red; font-weight: bold; text-decoration: none;"></ins></div></td></tr> <tr><td colspan="2">&nbsp;</td><td class='diff-marker'>+</td><td style="background: #cfc; color:black; font-size: smaller;"><div><ins style="color: red; font-weight: bold; text-decoration: none;">== Classes aren't Entry Points ==</ins></div></td></tr> <tr><td colspan="2">&nbsp;</td><td class='diff-marker'>+</td><td style="background: #cfc; color:black; font-size: smaller;"><div><ins style="color: red; font-weight: bold; text-decoration: none;"></ins></div></td></tr> <tr><td colspan="2">&nbsp;</td><td class='diff-marker'>+</td><td style="background: #cfc; color:black; font-size: smaller;"><div><ins style="color: red; font-weight: bold; text-decoration: none;">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.</ins></div></td></tr> <tr><td colspan="2">&nbsp;</td><td class='diff-marker'>+</td><td style="background: #cfc; color:black; font-size: smaller;"><div><ins style="color: red; font-weight: bold; text-decoration: none;"></ins></div></td></tr> <tr><td colspan="2">&nbsp;</td><td class='diff-marker'>+</td><td style="background: #cfc; color:black; font-size: smaller;"><div><ins style="color: red; font-weight: bold; text-decoration: none;">Always write an overview and include [[UseCase]]s in it. Only then navigate user to the actual [[Javadoc]] of your methods.</ins></div></td></tr> </table>

JaroslavTulach http://wiki.apidesign.org/index.php?title=Javadoc&diff=8668&oldid=prev 2015-12-30T15:08:13Z

<p></p> <table style="background-color: white; color:black;"> <col class='diff-marker' /> <col class='diff-content' /> <col class='diff-marker' /> <col class='diff-content' /> <tr> <td colspan='2' style="background-color: white; color:black;">←Older revision</td> <td colspan='2' style="background-color: white; color:black;">Revision as of 15:08, 30 December 2015</td> </tr> <tr><td colspan="2" class="diff-lineno">Line 1:</td> <td colspan="2" class="diff-lineno">Line 1:</td></tr> <tr><td class='diff-marker'>-</td><td style="background: #ffa; color:black; font-size: smaller;"><div>[[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.</div></td><td class='diff-marker'>+</td><td style="background: #cfc; color:black; font-size: smaller;"><div>[[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 <ins style="color: red; font-weight: bold; text-decoration: none;">final [[Xelfi]] project </ins>exams.</div></td></tr> </table>

JaroslavTulach http://wiki.apidesign.org/index.php?title=Javadoc&diff=8667&oldid=prev 2015-12-30T15:07:33Z

<p></p> <table style="background-color: white; color:black;"> <col class='diff-marker' /> <col class='diff-content' /> <col class='diff-marker' /> <col class='diff-content' /> <tr> <td colspan='2' style="background-color: white; color:black;">←Older revision</td> <td colspan='2' style="background-color: white; color:black;">Revision as of 15:07, 30 December 2015</td> </tr> <tr><td colspan="2" class="diff-lineno">Line 1:</td> <td colspan="2" class="diff-lineno">Line 1:</td></tr> <tr><td class='diff-marker'>-</td><td style="background: #ffa; color:black; font-size: smaller;"><div><del style="color: red; font-weight: bold; text-decoration: none;">#REDIRECT </del>[[wikipedia::javadoc]]</div></td><td class='diff-marker'>+</td><td style="background: #cfc; color:black; font-size: smaller;"><div>[[wikipedia::javadoc<ins style="color: red; font-weight: bold; text-decoration: none;">|Javadoc</ins>]] <ins style="color: red; font-weight: bold; text-decoration: none;">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.</ins></div></td></tr> </table>

JaroslavTulach http://wiki.apidesign.org/index.php?title=Javadoc&diff=2196&oldid=prev 2009-03-27T20:31:59Z

<p>Redirecting to <a href="http://en.wikipedia.org/wiki/javadoc" class="extiw" title="wikipedia:javadoc">wikipedia:javadoc</a></p> <p><b>New page</b></p><div>#REDIRECT [[wikipedia::javadoc]]</div>

JaroslavTulach