• Post Reply
  • Bookmark Topic Watch Topic
  • New Topic

documentation , how far should we go ?

 
Sam Stackly
Ranch Hand
Posts: 109
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
Hi guys,
I am almost done with the code and ready for documentation (my favorite part ), I don't know how far should I go ? just method and class or I have to have comments for each field too?
Thanks for your comments!!
Sam
 
Michael Morris
Ranch Hand
Posts: 3451
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
Hi Sam,
Well I javadocced (is that a word?) everything but am not sure if it is necessary. You should certainly document any public field and probably any protected field. I lost a point on documentation, so you probably need to get some other opinions on this.
Hope this helps,
Michael Morris
 
Sam Stackly
Ranch Hand
Posts: 109
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
Thanks Michael,
I agree with about public and protected fields, let's see if we get more comments on this
Sam
 
John Smith
Ranch Hand
Posts: 2937
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
Documentation also means source code comments. In the assignment requirements document, Sun puts one of the requirement in bold to the effect that your design decisions must be described in your source code comments.
Also, don't forget to include user doc (different from readme.txt and design choices document), -- some people missed it.
Eugene.
 
Sam Stackly
Ranch Hand
Posts: 109
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
Eugene,

Also, don't forget to include user doc (different from readme.txt and design choices document)

By user doc, do you mean help(like online help)?
Sam
 
John Smith
Ranch Hand
Posts: 2937
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator

By user doc, do you mean help(like online help)?

Yes, it's your choice, -- either plain text or online document will do it.
Eugene.
 
Sam Stackly
Ranch Hand
Posts: 109
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
Thanks Eugene,
I was thinking about online help , but wondering how can I use html doc inside of frame, sorry my knowledge is poor in this area.
any idea?
Thanks again
 
Nate Johnson
Ranch Hand
Posts: 301
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
A JEditorPane can load an HTML file. Just pop one of those into a scroll pane that is on a frame or a dialog and you will be ready to go... almost anyway. You will also need HyperlinkListeners to make your links work.
 
Michael Morris
Ranch Hand
Posts: 3451
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
Just like Nate said, JEditorPane is your man. Even though it's probably the most notorious swing class on the Java Bug Parade, it does a pretty decent job of displaying HTML. I used a FRAMESET style document scheme and discovered that if the user double-clicked between the contents document and the display document a NPE was thrown. Of course, why should a user double-click there anyway?
Michael Morris
 
cindy sung
Ranch Hand
Posts: 34
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
Hi,
I don't think it is necessary to add in so many complexities. Just keep it simple. An online is help in JEditorPane should be very very brief and simple html even without any links can do, which should be graded as part of GUI. And seperate user docs should be provided. They are targeted at different users.
cindy
 
  • Post Reply
  • Bookmark Topic Watch Topic
  • New Topic