Win a copy of The Little Book of Impediments (e-book only) this week in the Agile and Other Processes forum!
  • Post Reply
  • Bookmark Topic Watch Topic
  • New Topic

documentation tips

 
dean tomlinson
Ranch Hand
Posts: 94
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
with regards to the javadocs...
is it enought just to document the api, or should we be describing how the classes work - collaborate ? and usung this as one of the main ways to describe our designs ?
is it necessary to do an overview ?
my time has almost run out - gonna sit the exam tommorow and haven't even half finished the documentation. (and it's too late to cancel the exam)
any tips to save me time are v much appreciated.
ps - i recommend leaving plenty of time to do the documentation properly - it takes longer than you think !
 
Mark Spritzler
ranger
Sheriff
Posts: 17278
6
IntelliJ IDE Mac Spring
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
/**
* This class provides the foundation/main class of the server. It uses two
* other support classes: ServerGui and Data.
*
* @version 1.0 7-Oct-2001
*/

That is the javadoc I had on my ConnectionEngine. So you do want a brief descriptions of what the class does, and maybe what other classes it uses.
But as you can see I did it simply and not overboard.
Mark
 
Reid M. Pinchback
Ranch Hand
Posts: 775
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
So, inquiring minds want to know - what mark did you get on the SCJD, in particular, on comments?
 
Mark Spritzler
ranger
Sheriff
Posts: 17278
6
IntelliJ IDE Mac Spring
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
I got perfect on comments. The only place I lost points was a 49/53 on the server. final score 151/155
Mark
 
Reid M. Pinchback
Ranch Hand
Posts: 775
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
We're not worthy, we're not worthy....
 
Reid M. Pinchback
Ranch Hand
Posts: 775
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
For the public methods, does Sun expect all the parameters, return types, exceptions to be documented? In other words, just like Sun's own API docs? Mark, I'm particularly curious what you found to be the case.
 
Mark Spritzler
ranger
Sheriff
Posts: 17278
6
IntelliJ IDE Mac Spring
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
For the public methods, does Sun expect all the parameters, return types, exceptions to be documented?

Yes that is the case, just use the Javadocs that they provided in the Data classes code as examples.
Adding all that information is very easy, just can be a little time consuming.
Mark
 
  • Post Reply
  • Bookmark Topic Watch Topic
  • New Topic