WRITING JAVADOC COMMENTS
is an industry-wide standard developed by Sun for commenting Java programs,
and also a special tool included with the Java SDK which extracts these
comments from your Java files to create documentation - these are the
pages that you will see when you go to the Java documentation on Sun's
website. The comments MUST be set off with
the /** ....... */ style of comments to be included by javadoc; other
types of comments (both '/*....*/' and '//') are ignored. More information
about Javadoc can be found in Savitch, Appendix 4, and also at Sun's
Javadoc Home Page.
Your name should be designated with the @author tag; if you wish to include the date last modified, do so with the @version tag. Leave a blank line between the end of your description and the '@tags'. NOTE that these tags consist of the '@' symbol - no space after - followed by a specific label, then one or more spaces and the information related to the tag.
except main should have its own block of comments just BEFORE
the declaration, set off by the
If your method passes any parameters, or returns a value, you will need to also include the javadoc tags for parameters or return values. NOTE that you must insert a blank line before the "@tags", and then list and describe them. DO NOT list local variables in these tags, only values which are included in the argument list or are returned. Return tags do not need the variable name. When we cover exceptions, they are also listed with an @exception tag IF THEY ARE THROWN AND NOT HANDLED (CAUGHT) IN THE CURRENT METHOD.
List the parameter tags first, include the parameter's variable name, and a brief description of what the variable holds. The @return tag doesn't need a variable name, but should describe what is being returned. You do NOT need @return tags for void methods, or @param tags for methods that don't receive any parameters. Within the method, include short comments using the // marker, to indicate things that are being set or changed.
Running Javadoc on Unix:
Now, change directories and go inside the directory containing your java files. To run Javadoc on a specific file, type this command:
create the javadoc files in your docs directory in public_html
(the '-d' flag tells the javadoc compiler where to put the files). You'll
see a few messages as the files are created. If you want to run javadoc
on the entire directory, change to a location just outside it, and instead
of typing a single filename in the javadoc command, type the directory
command (a Unix command) sets the permissions on your files to determine
who can view them and through what mechanism. Note that directories
will be set with the number 755, while files (ANY text or HTML file,
or java file) will be set with the number 644.
Running Javadoc on Your Home PC:
This will be much easier than all the above, but you'll only be able to view your javadoc files on your local computer system.
If you want to see your files on FAS, you'll need to create the directory structure described above, then FTP all your doc files up into those directories and change their permissions with the chmod command.