 |
Home | Changes | Index | Search | Go
Notes on writing JavaDoc for SwingLabs projects.
Basics
Writing javadoc is tedious. For me the most annoying thing about it is that there are always the same "little" questions cropping up (like "where goes the @see tags, before or after the @param?") To answer these it greatly helps to follow a cookbook - SwingLabs projects use Sun's guidelines: How to Write Doc Comments for the JavaDoc Tool? . Be sure you have a copy handy when writing docs - it shows if you didn't
Additions
As helpful as the guidelines are, they don't cover everything. So here's a place where we can collect notes, experiences, does and donts...
Getters/Setters
Properties typically have three places to document: the field, the getter, the setter. The question of where to document what and to what extent re-appeared with every single property, so I decided to think about those as I would think about creating code: mimimize duplication, maximize consistency.
- getters/setters use the same/very similar first sentence, the field's comment is the same/similar phrase
- the setter has the most complete information
- the default value is part of the setter doc
- getter/setter have @see tags to each other.
- if there are @see tags to other, related methods they go into the setter.
- the method sequence: first getter, second setter (not really a doc, but a code convention)
One problem I couldn't solve: The first sentence often is very short (and uninformative): Gets/Sets the xx property. Any idea how to improve?
Links
|