Documentation

1
Documentation

• Javadocs

2
Design/Documentation
Recall

• 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
Example
Recall

• 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
• _at_author
• _at_revision
• _at_parameter
• _at_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.
• ltBRgtltBgtPreconditionlt/Bgt Precondition goes
  here
• ltBRgtltBgtPostconditionlt/Bgt Postcondition goes
  here
• _at_param p1 A description of this parameter
• _at_param p2 A description of this parameter
• _at_ 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
10
(No Transcript)