Granny's Programming Pearls
"inside of every large program is a small program struggling to get out"
JavaRanch.com/granny.jsp
  • Post Reply
  • Bookmark Topic Watch Topic
  • New Topic

Documenting the Data class methods

 
David Mullens
Greenhorn
Posts: 23
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
Hi All,
In the specifications, it says that our Data client will implement the same public methods as the Data class.
So...what is expected in the way of documenting this in the Data Client. The logic is still in the Data class. Part of me just wants to copy the same JavaDoc from the Data class and put it in my Data Client...then the other part of me wants to basically say the method in the Data client simple class the method calls the method in the data class.
Any insights are appreciated.
Dave.
 
Roman Rytov
Ranch Hand
Posts: 75
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
I'll tell u what I did (although I haven't uploaded yet).
I created an interface DataIfc defining all public methods of Data class. I extended Data class by DataEx class that implements DataIfc.
Since all interface's methods are documented I needed a few additional lines of text to explain deeper behaviour of some of functions.
But to write documentation of the interface I used existing docs from Data class a lot.
 
Kalichar Rangantittu
Ranch Hand
Posts: 240
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
Adding to javadoc, I have a question, is it ok to document private variables? The classes provided do no do that. I personally like it as it provides meaning and purpose of what a variable is for. Any views and thoughts please.
 
Roman Rytov
Ranch Hand
Posts: 75
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
I don't agree to document private part of a class. API doc is for an exterior programmer. He's not supposed to see your source hence he won't be able to access any of private methods/property.
"meaning and purpose of what a variable is for" may be achived through design doc (that is not for external usage maybe) or through source comments.
It's not the rule. Just my 0.02 NIS:-)
 
Anonymous
Ranch Hand
Posts: 18944
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
The documentaion on the javadoc tool describes the following feature which might be of use with an interface having all
the public methods of the Data class:
[http://java.sun.com/j2se/1.3/docs/tooldocs/win32/javadoc.html]
Automatic Reuse of Method Comments
Javadoc has the ability to automatically reuse or "inherit" method comments. If a method in a class or interface
has no doc comment or tags, Javadoc will instead use the comment and tags from a method it either overrides or implements,
if any, according to the algorithm below.
[/http://java.sun.com/j2se/1.3/docs/tooldocs/win32/javadoc.html]

One *could* move all the method comments for the public methods to the parent interface.
Regards,
S. Bro
 
Kalichar Rangantittu
Ranch Hand
Posts: 240
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
The provided code, namely Data class javadocs it private methods but not its private variables. This is inconistent in my belief. Please correct me if I am wrong.
 
Roman Rytov
Ranch Hand
Posts: 75
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
It doesn't matter. I prefer not to include anything related to the private part. Neither methods nor variables. I don't see any meaningful point for it. Look at any API doc from SUN. No docs for private part.
Hey folks, join me in discussing overall questions about uploading process.
Summary of uploading process
[ February 25, 2002: Message edited by: Roman Rytov ]
 
  • Post Reply
  • Bookmark Topic Watch Topic
  • New Topic