javadoc-umenting privates?

[Serkan Yazici]

Hi guys (and gals),

This is my first post in this forum, yet I feel like I've already know most of you by reading the forum inside out the past two weeks. A big thanks for all the insights you've given me.

Now, I'm almost done with my project but I'm not sure if should generate javadocs for my privates (...really, I mean methods and attributes...). I know it is not the general practice for public APIs that you provide to others, but for this project, I think javadoc is also for giving the assesor an idea on what the classes do and how. And I think the documentation should be more of a technical one. Most of the real work done by my classes is using private members. For example, my Client class that is responsible for creating/displaying/running the client window has only one public member: createGUI. All the work is done internally.

Oh, my instructions say:

javadoc style comments must be used for each element of the public interface of each class. You must create a full suite of documentation for the classes of the completed project.

Now that says, "must be used for each element of the public interface", but doesn't say "must not be used for other levels".

What do you think?

And thanks again for all the info here.

[Andrew Monkhouse]

Hi Serkan,

Welcome to JavaRanch and this forum.

I am one of those who does document all levels of all my classes, and I did so in my submission (and got 100% for documentation). But I know that others have submitted without providing javadoc for non public methods and they also received 100% for documentation. So it appears that you don't have to do this.

I would still recommend having some documentation on all your methods, but you may not need to have full javadoc style comments.

Regards, Andrew

[Serkan Yazici]

Thanks Andrew,

Good to be here.

I think I should have rephrased my question as "should I generate javadocs for private classes and members?". I commented everything in the code (javadoc style) - God, it took me longer than coding the stuff. I wasn't sure whether or not to expose them in the generated documents.

Anyways, after thinking about it a little more, I settled for generating javadocs for all package-level and public classes/members (I don't really have any protected members).

Thanks for your reply. Now back to completing and polishing up the user guide and design choices.

-- Serkan

[Nathaniel Stoddard]

I also created javadocs for all levels of my code. I forget whether my final api javadocs were for all levels, or only the public though. I'd imagine at that point it wouldn't matter -- the grader is not likely to notice that some are private when spending her two minutes looking at your javadocs, but will likely notice your thoroughness when browsing your source.