B&S: javadoc

[Michael Cox]

Hi,

Bodgitt and Scarper 2.1.1

"...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 find the above requirement confusing so I have written javadoc comments for every class, method and field private or public or otherwise.

(which amount to 579 pages when viewed as PDF - though I do have 150 classes).

Should I only generate javadoc html with -public to avoid sending too much?

Many thanks for any advice.

Michael

[Roman Yankin]

I don't think that verbose documentation is a bad idea, however it is common practice to provide documentation to public and protected methods/fields within javadoc. Comments for private elements are useful for developers but not the users of your code.
Another thing to keep in mind is that it is suggested to have the size of the archive with assignment around 400Kb (as far as I know such warning is sent out when you request the upload instructions)

[Jo�o Batista]

I agree that the verbose documentation is not a bad idea at all (I wrote javadoc for everything as well), but that number "150" seems a bit exaggerated.
I believe you could do some refactoring. At least to guarantee less errors.

[Michael Cox]

Damn - I was so busy focussing on the assignment instructions I totally overlooked the 200K-400K recommendation from the assignment email.

Thanks very much for pointing that out.

Michael

[Michael Cox]

My assignment jar is 2.5Mb :-(

So I'm in big trouble. I'm going to boil my code to reduce but also..

The part of the jar occupied by the javadoc is huge I'm sure I can make savings but of course the assignment javadoc instructions are incomplete, contradictory etc:

Javadoc style comments must be used for each element of the public interface of each class

OK - no problem with that.

You must create a full suite of documentation for the classes

I must do it - but what do I read into "full suite". Can I turn off javadoc index, tree and use to save a bit of space or would that not be considered to be full suite?

provide javadoc documentation for all classes you write...subdirectory containing javadoc documentation for all classes and interfaces you are submitting

Many of my classes are private inner classes or package protected classes. If I use -public modifier when generating javadoc these classes will be skipped. if I use -private than I'm reporting on private members too.

Does this mean I'm going to have to make all my classes public - that would seem very bad OO.

Michael

[Jeffry Kristianto Yanuar]

I create all the documentation for all access modifier including private. You said you have 150 classes, I think you overcomplicated your solution. You have to refactor it.


Hope that helps

Jeffry Kristianto Yanuar
Java Instructor
SCJP 5.0
SCJA
SCJD (Working on UrlyBird 1.3.2) --> Ready to submit