• Post Reply
  • Bookmark Topic Watch Topic
  • New Topic

Documentation Tips - Javadoc

 
Terry McKee
Ranch Hand
Posts: 175
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
I found some things useful as I began checking over the comments in the supplied code. Since it is worth 20pts (as well as some points in General Considerations) I thought I would share my findings. First of all, let me mention that I used the DocCheck Utility available at http://java.sun.com/j2se/javadoc/doccheck/ to locate problems within the sourcecode. Though it is in beta and certainly not able to locate all errors, it was very good at finding things that I probably would have overlooked on my own.
Things that did come up frequently in the supplied code were the following:
1) Improper tag - Used @returns instead of @return
2) Improper usage - Used @param type name instead of @param name description (Within the description the type is usually specified.
3) Missing tags - omit @return
4) Improper names - Named parameter (in @param tag) doesn't match up with the actual name within the method declaration.
5) Missing commments altogether - all public classes/interfaces methods, and variables should have comments -- the supplied code, that I received, has missing comments.
Some of this probably goes without saying, but I found some of the errors within the comments particularly sneaky, that probably would have gone unnoticed without a more detailed look.
 
Ricardo Polero
Ranch Hand
Posts: 128
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
Thx for the tip, Terry !
 
  • Post Reply
  • Bookmark Topic Watch Topic
  • New Topic