Win a copy of AWS Security this week in the Cloud/Virtualization forum!
  • Post Reply Bookmark Topic Watch Topic
  • New Topic
programming forums Java Mobile Certification Databases Caching Books Engineering Micro Controllers OS Languages Paradigms IDEs Build Tools Frameworks Application Servers Open Source This Site Careers Other all forums
this forum made possible by our volunteer staff, including ...
Marshals:
  • Campbell Ritchie
  • Paul Clapham
  • Jeanne Boyarsky
  • Junilu Lacar
  • Henry Wong
Sheriffs:
  • Ron McLeod
  • Devaka Cooray
  • Tim Cooke
Saloon Keepers:
  • Tim Moores
  • Stephan van Hulst
  • Frits Walraven
  • Tim Holloway
  • Carey Brown
Bartenders:
  • Piet Souris
  • salvin francis
  • fred rosenberger

Documentation Tips - Javadoc

 
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.
 
Ranch Hand
Posts: 128
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
Thx for the tip, Terry !
 
Rototillers convert rich soil into dirt. Please note that this tiny ad is not a rototiller:
Devious Experiments for a Truly Passive Greenhouse!
https://www.kickstarter.com/projects/paulwheaton/greenhouse-1
    Bookmark Topic Watch Topic
  • New Topic