• Post Reply Bookmark Topic Watch Topic
  • New Topic
programming forums Java Mobile Certification Databases Caching Books Engineering Micro Controllers OS Languages Paradigms IDEs Build Tools Frameworks Application Servers Open Source This Site Careers Other Pie Elite all forums
this forum made possible by our volunteer staff, including ...
Marshals:
  • Campbell Ritchie
  • Ron McLeod
  • Paul Clapham
  • Devaka Cooray
  • Tim Cooke
Sheriffs:
  • Rob Spoor
  • Liutauras Vilda
  • paul wheaton
Saloon Keepers:
  • Tim Holloway
  • Tim Moores
  • Mikalai Zaikin
  • Carey Brown
  • Piet Souris
Bartenders:
  • Stephan van Hulst

Documentation Question

 
Ranch Hand
Posts: 30
  • Mark post as helpful
  • send pies
    Number of slices to send:
    Optional 'thank-you' note:
  • Quote
  • Report post to moderator
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
 
Ranch Hand
Posts: 619
  • Mark post as helpful
  • send pies
    Number of slices to send:
    Optional 'thank-you' note:
  • Quote
  • Report post to moderator
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.

 
Roy Augustine
Ranch Hand
Posts: 30
  • Mark post as helpful
  • send pies
    Number of slices to send:
    Optional 'thank-you' note:
  • Quote
  • Report post to moderator
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.
 
Ranch Hand
Posts: 32
  • Mark post as helpful
  • send pies
    Number of slices to send:
    Optional 'thank-you' note:
  • Quote
  • Report post to moderator
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
Posts: 619
  • Mark post as helpful
  • send pies
    Number of slices to send:
    Optional 'thank-you' note:
  • Quote
  • Report post to moderator
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
Posts: 32
  • Mark post as helpful
  • send pies
    Number of slices to send:
    Optional 'thank-you' note:
  • Quote
  • Report post to moderator
yes! this does it just fine!
 
When I was younger I felt like a man trapped inside a woman’s body. Then I was born. My twin is a tiny ad:
Smokeless wood heat with a rocket mass heater
https://woodheat.net
reply
    Bookmark Topic Watch Topic
  • New Topic