JavaDoc
JavaDoc is the first of many documentation tools, and the inspiration of much of what you see on this site. The javadoc approach is to encourage software developers to document their code while they are developing it. JavaDoc then generates an HTML version of some nice documentation.Most IDEs will automatically generate JavaDoc documentation. Here you will see how to use JGrasp to generate it.
Creating a Project in JGrasp
If you do not have JGrasp, you can get it here. Once you have it installed, you can open JGrasp and start a project.
The first step in starting a project in jGrasp is the one where most people screw things up. Simply stated, every time you think of a project you should think of the project having a home directory. For some projects the resources might be all over the place, but it should have a folder to call home. So, the first step is to use jGrasp's Project menu, select a new project, and bring up the new project window. Before you type in the name for the project, make sure the New Project window is showing you the directory you want to be this project's home directory,enter a name for the project and press the Create button. The project should now appear as an entry in its home directory.
At this point all we did was create a project, what will be one of many projects. Only one project may be open at a time, so the next thing you have to do it open a project when you want to work with it. Pull down the Project menu, select Open, browse through the Open Project find the directory that contains the project you want to open, select the project, and press Open.When you select a project, the Open Projects window will displat the project and its contents, if any.
While a project is open, as you develop resources for a project you must add these resources to the project by highlighting an item, pressing the alternate mouse button, and selecting the Add to Project from the pulldown menu. As a project grows all you have to do is make sure you have added all items to the project. Try to keep a project up to date by adding or removing entries in a timely fashion. One of the benefits of carefully managing a project is the ease with which you will be able to construct javadoc documentation for that project. At a minimum, make sure all inerface and classe (.java) files that are part of a project have been added to the project.
See a full tutorial with screen shots here, on Dr. Beidler's Site
Using JavaDoc
javadoc comments are placed in the source code, they have a simple format:
- javadoc comments begin with
/**and end with*/ - A javadoc comment for any item (class, method, or attribute) immediately precedes that item
- There are special
@codes, most notably those associated with methods (@param, @throws, and @return). Use them carefully, completely, and well. Using the@codes carefully will have a very positive effect on the documentation you generate with javadoc. - Get in the habit of including pre and post conditions with each method and try to follow that up with well conceived assertions and exception handling.
Once you have created the javadoc comments, getting the documentation is easy, just pull down the Project menu, select Generate Documentation, presto, your done.
Any time you want to see the documentation, just go to the Project menu and select Show Documentation. jGrasp will bring up its own browser and display the documentation. You elaborate on your documentation by improving your javadoc comments and regenerating the documentation. You can do this everytime you enhance the software - adjust the comments to meet the software, and regenerate the documentation.
See a full tutorial with screen shots here, on Dr. Beidler's Site