Disallowed to use private inner classes?

[Mogens Nidding]

The reason I am asking is that I have this in my requirements:

The JAR file must have the following layout and contents in its root:

The a directory called docs, containing the following items at the top level:

... A subdirectory called javadoc, containing HTML/Javadoc documentation for all classes and interfaces you are submitting

Now, if I have a private inner class somewhere, this would force me to generate documentation right down to the private level, which I certainly not something I wish to do.

Does anyone know if this is a problem?
If it is, I guess I'll just make the class package private.

[James Turner]

I use some default access classes and no Javadoc is generated for them.

I am wondering if that would be allowed. But if its part of the design and Javadoc does not document them, then thats not a problem I surpose.

[Jay Bromley]

Hello there,

The instructions do read "all classes and interfaces" so I'm taking it at face value and documenting everything. It's a little bit more writing, but I tend to write most of the comments first, so no big deal. I do, by the way, have private inner classes (ActionListeners.)

javadoc has the -public, -protected, -package and -private switches to determine what javadoc generates documentation for. Per the previous comment, I'm thinking I have to use -private.

Regards,
Jay
[ October 15, 2004: Message edited by: Jay Bromley ]

[Gaz Smith]

The following is from the documentation sub-section within the Application Overview of my instructions.

The code itself should be as clear as possible; do not provide comments that do not add to the comprehensibility of the code. Awkward or complex code should have descriptive comments, and 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. This must be generated using the tool "javadoc" and must be in HTML format. Provide javadoc documentation for all classes you write...

I think commenting the 'public interface' is the way forward :-)

[James Turner]

Hi there,

By saying:

Awkward or complex code should have descriptive comments, and javadoc style comments must be used for each element of the public interface of each class.

Then saying:

Provide javadoc documentation for all classes you write...

It is contradicting itself. Even so I think that only public interface classes and methods need to be documented with Javadoc, private methods and classes should be anonymous to the clients of the code in any respect, after all this is one of the main points of object orientation.

James.

[Gaz Smith]

It is contradicting itself.

..and not for the first time I'm sure you'll agree! :roll:

I think this is the 'common sense' solution though. You could even document the decision to document!

p.s. I'm currently reading Refactoring: Improving the Design of Existing Code by Martin Fowler. It's a good read that encourages the development of self describing code. i.e. Only put comments (non-javadoc) where necessary for clarity and if they're needed at all then the first step is probably to assess why the code is so complex as to not be readable. Bit off subject but this reminded me of it