Granny's Programming Pearls
"inside of every large program is a small program struggling to get out"
JavaRanch.com/granny.jsp
The moose likes Developer Certification (SCJD/OCMJD) and the fly likes Documentation Question Big Moose Saloon
  Search | Java FAQ | Recent Topics | Flagged Topics | Hot Topics | Zero Replies
Register / Login
JavaRanch » Java Forums » Certification » Developer Certification (SCJD/OCMJD)
Bookmark "Documentation Question" Watch "Documentation Question" New topic
Author

Documentation Question

Roy Augustine
Ranch Hand

Joined: Jul 08, 2003
Posts: 30
Hi all
My assignment says

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.

1. What is that full suite of documentation means?
2. Just sending suncertify directory generated by javadoc meets the requirement ?
Suncertify directory contains subdirectories for each package and each subdirectory contains html documentation for each class of that directory.

Or I also need to send other html files generated by javadoc like allclasses-noframe, allclasses-frame,... ?
3. Whether I need to provide package level documentation?
4. whether I need to provide documentation for inner classes which are not public ?
Thanks in advance.
Roy
George Marinkovich
Ranch Hand

Joined: Apr 15, 2003
Posts: 619
Hi Roy,
Originally posted by Roy Augustine:

1. What is that full suite of documentation means?
2. Just sending suncertify directory generated by javadoc meets the requirement ?
Suncertify directory contains subdirectories for each package and each subdirectory contains html documentation for each class of that directory.

Or I also need to send other html files generated by javadoc like allclasses-noframe, allclasses-frame,... ?

Send everything in the output directory (specified by -d) generated by the javadoc command.

3. Whether I need to provide package level documentation?

Probably not absolutely required, but I would do it anyway. It doesn't really involve much work, just one html file per package. I'm assuming your talking about the package.html files. You might also want to provide an overview.html file to explain how the package work together (again, probably not required, but it's just one html file and it doesn't take long to do).
If your talking about javadoc -package instead, then the answer depends on how restrictive you've been with your access. If you made almost everything in your design package-private then you probably do want to use javadoc -package; otherwise javadoc (using the default -protected switch) will be OK.

4. whether I need to provide documentation for inner classes which are not public ?

You're probably not required to provide documentation for anything that's not public (or protected). I think it's a good thing to provide javadoc documentation for everything in the code, but it's probably not reqired.


Regards, George
SCJP, SCJD, SCWCD, SCBCD
Roy Augustine
Ranch Hand

Joined: Jul 08, 2003
Posts: 30
Hi George
Thanks a lot for your quick reply.
I know what you mean, play safe. I been thinking that way too since it doesn't involves much work.
I'm assuming your talking about the package.html files.
Yes. My question was about .html file.
Thanks again
Roy.
Rolf Johansson
Ranch Hand

Joined: Feb 25, 2004
Posts: 32
I'm having trouble understanding how the package.html file is supposed
to work. Presently, I have 1 package.html in the same directory as
my source code, for example, for these 2 packages, I have:

Each of these give a "package-level" description of their respective package. Next, I generate the javadoc files for the suncertify.comm package by:

This creates a scjd/html/suncertify/comm directory with all the .html
files for the package in it. In addition, it creates a bunch of files
in scjd/html, 1 of which is index.html, which contains the package
comments I included in scjd/code/suncertify/comm/package.html as well as
links to the suncertify.comm package documentation.
Now my confusion comes when I then issue a similar command for another package, for example:

This creates a subdirectory scjd/html/suncertify/util as expected, but the index.html created when I ran javadoc on suncertify.db is overwritten! So how do I run javadoc so each package's package.html is added to the overall documentation tree? I guess I am not placing it in the correct directory?
Any help is appreciated!
- Rolf.
George Marinkovich
Ranch Hand

Joined: Apr 15, 2003
Posts: 619
Hi Rolf,
My suggestion, generate the javadoc for your entire project at the same time:
createDoc.bat
==============
javadoc @options @packages
options
==============
-classpath scjd/classes
-d scjd/docs
-overview scjd/code/suncertify/overview.html
-sourcepath scjd/code
packages
==============
suncertify.comm
suncertify.db
...
Rolf Johansson
Ranch Hand

Joined: Feb 25, 2004
Posts: 32
yes! this does it just fine!
 
 
subject: Documentation Question
 
Similar Threads
NX: Should I reformat the provided interfaces comments?
am I using the javadoc tool correctly
java doc for private members
Javadoc documentation??
Thoughts wanted READMDE.txt