I have in fact done this as followed the example source file in the java coding conventions produced by Sun but when I run javadoc I don't see any of my private members displyed in the resulting html. My instructions say that I must provide javadoc for the public interface but am not sure what I should with my existing private member doc comments. Any input much appreciated. Many thanks Sam
The default behaviour of javadoc is to only generate documentation for classes, interfaces, and members that have protected or public scope. Use the -private option to generate documentation for everything. Other options are -package, -protected (the default) or -public. Just type javadoc with no parameters for a full list of options. I use javadoc comments for all classes, interfaces, and members, regardless of scope - because I think its good style. Not sure what you should submit to Sun though - I suspect the default behaviour is probably most appropriate because it only details what clients of your API can get at. Hope this helps.
Hi Sam I also had JavaDoc comments on all private methods and variables. For my submission, I used standard Javadoc (I did not specify '-private'). I got 100% for documentation doing this. Regards, Andrew
Thanks guys. In that case I will leave all my javadoc comments as they are in my code and just submit the public API for documentation. I have also explicitly put doc comments in for each class that implements an interface rather than letting javadoc just inherit them as I think it makes an explanation of the code more readily available for any future programmer so they don't have to go to the javadoc or find the explanation in the interface. Do you think I will be penalized for this? Many thanks Sam
I don't think you'll be penalized Sam, but IMO, it's good practice to document all methods, private or otherwise. It forces you to exaimine exactly what the method is doing for you, what you expect as preconditions, and what you expect as post conditions. All best, M