documentation , how far should we go ?

[Sam Stackly]

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]

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]

Thanks Michael,
I agree with about public and protected fields, let's see if we get more comments on this
Sam

[John Smith]

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]

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]

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]

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]

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]

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]

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