Win a copy of Testing JavaScript Applications this week in the HTML Pages with CSS and JavaScript forum!
  • 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 all forums
this forum made possible by our volunteer staff, including ...
Marshals:
  • Campbell Ritchie
  • Bear Bibeault
  • Ron McLeod
  • Jeanne Boyarsky
  • Paul Clapham
Sheriffs:
  • Tim Cooke
  • Liutauras Vilda
  • Junilu Lacar
Saloon Keepers:
  • Tim Moores
  • Stephan van Hulst
  • Tim Holloway
  • fred rosenberger
  • salvin francis
Bartenders:
  • Piet Souris
  • Frits Walraven
  • Carey Brown

Documentation Question

 
Ranch Hand
Posts: 30
  • Mark post as helpful
  • send pies
  • 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
  • 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
  • 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
  • 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
  • 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
  • Quote
  • Report post to moderator
yes! this does it just fine!
 
I once met a man from Nantucket. He had a tiny ad
Building a Better World in your Backyard by Paul Wheaton and Shawn Klassen-Koop
https://coderanch.com/wiki/718759/books/Building-World-Backyard-Paul-Wheaton
    Bookmark Topic Watch Topic
  • New Topic