Documentation Javadocs. Design/Documentation An essential ingredient of good Object Oriented...
-
Upload
elmer-murphy -
Category
Documents
-
view
212 -
download
0
description
Transcript of Documentation Javadocs. Design/Documentation An essential ingredient of good Object Oriented...
![Page 1: Documentation Javadocs. Design/Documentation An essential ingredient of good Object Oriented programming is known as design by contract. This means that.](https://reader036.fdocuments.us/reader036/viewer/2022083119/5a4d1b3f7f8b9ab0599a049e/html5/thumbnails/1.jpg)
Documentation
Javadocs
![Page 2: Documentation Javadocs. Design/Documentation An essential ingredient of good Object Oriented programming is known as design by contract. This means that.](https://reader036.fdocuments.us/reader036/viewer/2022083119/5a4d1b3f7f8b9ab0599a049e/html5/thumbnails/2.jpg)
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
![Page 3: Documentation Javadocs. Design/Documentation An essential ingredient of good Object Oriented programming is known as design by contract. This means that.](https://reader036.fdocuments.us/reader036/viewer/2022083119/5a4d1b3f7f8b9ab0599a049e/html5/thumbnails/3.jpg)
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
![Page 4: Documentation Javadocs. Design/Documentation An essential ingredient of good Object Oriented programming is known as design by contract. This means that.](https://reader036.fdocuments.us/reader036/viewer/2022083119/5a4d1b3f7f8b9ab0599a049e/html5/thumbnails/4.jpg)
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.
![Page 5: Documentation Javadocs. Design/Documentation An essential ingredient of good Object Oriented programming is known as design by contract. This means that.](https://reader036.fdocuments.us/reader036/viewer/2022083119/5a4d1b3f7f8b9ab0599a049e/html5/thumbnails/5.jpg)
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.
![Page 6: Documentation Javadocs. Design/Documentation An essential ingredient of good Object Oriented programming is known as design by contract. This means that.](https://reader036.fdocuments.us/reader036/viewer/2022083119/5a4d1b3f7f8b9ab0599a049e/html5/thumbnails/6.jpg)
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
![Page 7: Documentation Javadocs. Design/Documentation An essential ingredient of good Object Oriented programming is known as design by contract. This means that.](https://reader036.fdocuments.us/reader036/viewer/2022083119/5a4d1b3f7f8b9ab0599a049e/html5/thumbnails/7.jpg)
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
![Page 8: Documentation Javadocs. Design/Documentation An essential ingredient of good Object Oriented programming is known as design by contract. This means that.](https://reader036.fdocuments.us/reader036/viewer/2022083119/5a4d1b3f7f8b9ab0599a049e/html5/thumbnails/8.jpg)
Results
![Page 9: Documentation Javadocs. Design/Documentation An essential ingredient of good Object Oriented programming is known as design by contract. This means that.](https://reader036.fdocuments.us/reader036/viewer/2022083119/5a4d1b3f7f8b9ab0599a049e/html5/thumbnails/9.jpg)
Results
![Page 10: Documentation Javadocs. Design/Documentation An essential ingredient of good Object Oriented programming is known as design by contract. This means that.](https://reader036.fdocuments.us/reader036/viewer/2022083119/5a4d1b3f7f8b9ab0599a049e/html5/thumbnails/10.jpg)