Documentation Standards for Module Generators

If all module generators are documented according to the standard outlined here they will have a uniform format and be much easier for people to use. To help, consult this sample file as you read along. Note that the example is there as a format example and may not be 100% functionally correct.

Here are some basic steps to get started:

1. Make your module generator files all part of package "byucc.jhdl.modgen". This implies that they have to live in a directory structure that ends with .../byucc/jhdl/modgen for things to work.
2. In your first javadoc comment at the top of your file, put in an H2 header called <H2>General Description</H2>. Eventually this heading will be replaced with the custom javadoc tag @general_description when the final documentation is generated using JDK 1.2.
3. Begin with a one sentence brief description suitable for use in a summary table. For example, the one sentence for the accumulator simply says: "An accumulator that allows a generic sized input and output. This sentence will eventually show up in a class summary table in the documentation.
4. Next include a block diagram, transition tables, timing diagrams, or other means to unambiguously describe your block. Remember that a picture is worth a thousand words. Keep your verbal functional descriptions to a minimum - they are nearly impossible to write unambiguously.
5. In each section of comments you add, remember that you are writing HTML. Thus, most HTML tags will work in here. Use them to get the formatting you want. See the example file mentioned above for an example. Also, below are listed a few HTML tutorials if you are interested in learning more about HTML.
6. If you want to further subdivide your general description section you may do so using level 3 and 4 headings (H3 and H4).
7. Draw any drawings you want on paper and have Jared Martin draw them in Canvas. He will output GIF or JPEG. Make the drawings black on white as in the example.
8. All references to images and the like are relative to the directory the source code files are in.
9. After the general description put in an H2 header called <H2>Implementation</H2>. This header will eventually be replaced with an @implementation javadoc tag for use with JDK 1.2. If there are technology-independent impelementation details you want to give, head them up with an H3 heading called "All Technologies". An example of this might be a description of how the pipelining is done (how the program chooses where to put the flip flops). Then, for each technology, put in an H3 heading which gives the technology name such as "Xilinx 4K". Under this put in H4 headings for "Area". The example included here has an applet to help the user compute the area required. For simple blocks, just state the height and width and the I/O locations. For more complex blocks, Russ can help you modify the applet to calculate the area.
10. Put in an "@author" tag and give yourself some credit.
11. Put in a "@version" tag and number your releases (see CVS NOTE below to learn how to have CVS automatically write this into your comment).
12. Document each constructor and method using the standard method tags and as shown in the example. The document writing_javadoc_comments gives a brief overview of the standard method javadoc tags.
13. Make sure your compute method is completely documented using javadoc conventions with @param tags and so forth. Make sure that any helper methods for your compute or any other methods specific to your class are private. For example, a sign_extend method should not be public.
14. Also document what your default simulation model is using a javadoc comment directly before you set the default simulation model in your class. The statement should go something along the lines of "The default simulation model is behavioral." (or structural if it's structural).

Generating Documentation

Follow these steps for JDK 1.1.* :

1. Go the the directory .../byucc/jhdl/modgen/ where your module(s) should be residing.
2. Execute the following from a command prompt:
       javadoc -version -author -notree -noindex your_design.java
3. View the page that was created in Netscape by typing:
   file:/.../byucc/jhdl/modgen/byucc.jhdl.modgen.your_design.html
   It should look something like this.

Follow these steps for JDK 1.2:

1. First replace the H2 headings <H2>General Description</H2> and <H2>Implementation</H2> with the javadoc tags @general_description and @implementation in your initial javadoc comment.
2. Call Russ and have him work with you to do it.

HTML Tutorials

CVS NOTE:

Created: 1/6/1999 by Brent Nelson
Last Updated: 5/28/1999 by Russell Fredrickson