1 / 10

Documentation

Documentation. Javadocs. Recall. Design/Documentation. An essential ingredient of good Object Oriented programming is known as design by contract. This means that before modules are written a specification or contract is written which states

dennis-mcclain
Download Presentation

Documentation

An Image/Link below is provided (as is) to download presentation Download Policy: Content on the Website is provided to you AS IS for your information and personal use and may not be sold / licensed / shared on other websites without getting consent from its author. Content is provided to you AS IS for your information and personal use only. Download presentation by click this link. While downloading, if for some reason you are not able to download a presentation, the publisher may have deleted the file from their server. During download, if you can't get a presentation, the file might be deleted by the publisher.

E N D

Presentation Transcript

  1. Documentation Javadocs

  2. Recall Design/Documentation • An essential ingredient of good Object Oriented programming is known as design by contract. • This means that before modules are written a specification or contract is written which states • What preconditions must be met for the module to properly function • What is the purpose of the module • What will be the state of things after the module executes which is known as the postconditions

  3. Recall Example • A module located in a Queue class which will dequeue the element at the head of the queue. • Precondition • The queue must be instantiated. It is recommended that isEmpty be run to assure that their is an element to dequeue • Purpose • Remove the element at the head of the queue and return it to the user. It will be an Object. • Postcondition • The queue will have one fewer element unless the queue was empty to start with in which case the method will return null and the queue will be unchanged

  4. Design/Documentation • Java comes with an excellent documentation tool called Javadoc • Usage of the Javadoc system requires following several steps • First special Javadoc block comments are added to source files. • Javadoc block comments start with /** and end with */ this they function like regular comments • Each class, field and method should be commented with a Javadoc comment just before the actual item.

  5. Javadoc • The comment should start with a short descriptive phrase followed by a period . • Then a longer description of the purpose of the item may be added. • HTML may be embedded • Special tags can be used such as @author @revision @parameter @return • The precondition and postcondition should be included.

  6. Javadoc • Once commenting is complete the Javadoc program is run from the OS prompt. • If for example a group of class files for a given project are located in the same directory then Javadoc may be run by typing javadoc *.java • When the program runs it will report any problems and will produce a series of HTML files documenting all classes, methods and fields. • A Javadoc template is on the next slide followed by a sample

  7. Javadoc Template /* -------------------------------------------------*/ /** Descriptive phrase. Longer statement of purpose. <BR><B>Precondition:</B> Precondition goes here <BR><B>Postcondition:</B> Postcondition goes here @param p1 A description of this parameter @param p2 A description of this parameter @ return A description of the return value */ public int someMethod(double p1, String p2) { return 0; } Note: The leading comment of “---” characters is not part of the Javadoc system but will make code easier to read

  8. Results

  9. Results

More Related