• Post Reply Bookmark Topic Watch Topic
  • New Topic

Documentation block formatting  RSS feed

 
Daniel Ortega
Greenhorn
Posts: 7
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
Hello all. I'm just getting started here, and want to develop a good documentation block template that I can use for my Java programs. There are many samples out there to choose from, but wondering what others here at JavaRanch use?

Here's what I have so far:


Suggestions for improvements?

Thanks.

Dan
 
Campbell Ritchie
Marshal
Posts: 56570
172
  • Likes 1
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
That isn't a documentation comment, because it doesn't start /**.
If you want a private format for internal use only, that is a block comment, but it cannot be used by the javadoc tool. That is suitable for recording author's name, etc., but it is probably better to put the purpose in a documentation comment. Leave out the multiple ----.
There is a conventional format for the javadoc tool, which you can read about here. Remember the @ tags go after everything else.
 
Knute Snortum
Sheriff
Posts: 4281
127
Chrome Eclipse IDE Java Postgres Database VI Editor
  • Likes 2
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
 
Stephan van Hulst
Saloon Keeper
Posts: 7992
143
  • Likes 2
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
Besides writing documentation the way Campbell and Knute have described, it's convention to write license headers at the start of the file in regular comment blocks. Here's an example using the GNU General Public License:
 
Campbell Ritchie
Marshal
Posts: 56570
172
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
Somebody copied the Sun/Oracle licence header for a Hello World program here. Slightly different from the GPL above, complete with dire warnings that if your computer blows up and throws you through the ceiling, it isn't their fault
 
  • Post Reply Bookmark Topic Watch Topic
  • New Topic
Boost this thread!