Software Documentation

1
Software Documentation

• Section 5.5 ALBINGs
• Section 6.1.4 JIAs
• Appendix B JIAs

2
Announcements

• Project Phase III-a, b c Prototype
• III-a 2 subcomponents due on Thursday 14th
• III-b 3 subcomponents due on Monday 18th
• III-c integration or driver due on Wednesday
  20th (BEFORE LONG WEEKEND)
• You are to build a working prototype for all
  subcomponents designed in phases I II.
• You are expected to implement all major classes
  (phases a b) along with a driver or system
  class (phase c).
• GUI is not part of the grade so spend your time
  designing better classes instead.
• Your code must be documented using JavaDoc and
  include all necessary code comments.
• Turn in a report which includes the UML design
  from phase II (with any updates - explain what
  changes youve made) and the HTML output of the
  JavaDoc utility (use private option)
• Additionally, email me the code in a tar file.

3
Announcements

• Evaluation Criteria
• Report clarity and organization 10
• JavaDoc output 20
• Adherence to UML design 20
• Code for component 1 10
• Code for component 2 10
• Code for component 3 10
• Code for component 4 10
• Code for component 5 10

4
Source Code Documentation

• HTML Basics http//www.w3schools.com/html/html_pr
  imary.asp
• Ubiquitous problems
• Writing API documentation for a system is one of
  the most unpleasant jobs a developer will ever
  face
• Application programming interface
• The kind of job that could drive you to despair
• No documentation ? no code
• Informal documentation isnt standard
• As software evolves, informal documentation and
  code become out of sync!
• Eventually, documentation becomes unusable making
  code hard to understand and update!

5
JavaDoc

• javadoc utility makes writing and maintaining
  code documentation up-to-date easier!
• Ships with JDK
• Defines a set of specially formatted comments
• Can be added to document each
• package,
• class ( interfaces),
• method, and
• field
• Used to generate HTML documentation of classes or
  packages after parsing the comments
• HTML documentation of the API

6
JavaDoc comments

• IMMEDIATELY precede the feature it describes
• Consist of
• Description of the feature
• Copied as is to the documentation page
• List of tags
• Formatted by javadoc in a consistent style
• Used in classes, interfaces, methods and
  variables
• Have the following format
• /
• Summary sentence.
• More general information about the
• program, class, method or variable which
• follows the comment, using as many lines
• as necessary.
• ltSPACEgt
• zero or more tags to specify more specific
  kinds
• of information, such as parameters and return
• values for a method
• /

7
JavaDoc comments

• Must be provided for every public class or
  interface
• Must be provided for each public method or
  constructor
• Why public?
• DBC

8
JavaDoc Tags

• _at_author name
• Name one of the authors of this class
• Use multiple tags if there are multiple authors
• Used in Class, Interface, Method 
• E.g. _at_author Jane Smith, lab X
• _at_version release
• Indicate the version of the software containing
  this class
• Used in Class, Interface

9
JavaDoc Tags

• _at_see target
• Point the reader at something else relevant to
  read, like another class or a specific method
• Inserts a link pointing to the target
• Used in All 
• _at_since release
• Indicates that this class has existed since the
  named release
• Used in All
• _at_deprecated text
• Marks the entity as deprecated and points the
  reader to what they should use instead via an
  _at_see tag
• Used in All

10
_at_see tag

• Points to another package, class, method, field
  or even URL
• javadoc creates a link
• The syntax for the text after _at_see depends upon
  what you're pointing to
• _at_see package ? Link to package
• _at_see classname ? Link to classname in the current
  package
• _at_see package.classname ? Link to classname in
  another package
• _at_see method ? Link to method in the current
  class
• _at_see method(type) ? Link to method with argument
• _at_see classnamemethod ? Link to method in another
  class
• Method in a class in a different package?
• _at_see lta hrefurlgttextlt/agt ? Link to URL

11
Examples

• //same class entities
• _at_see field
• _at_see Constructor(Type,...)
• _at_see method(Type, Type,...)
• //same package entities
• _at_see Class
• _at_see Classfield
• _at_see ClassConstructor(Type,...)
• _at_see Classmethod(Type,...)

• //different package entities
• _at_see package
• _at_see package.Class
• _at_see package.Classfield
• _at_see package.ClassConstructor(Type,...)
• _at_see package.Classmethod(Type, Type,...)
• //URL
• _at_see lta href"spec.htmlsection"gtJava Speclt/agt

12
JavaDoc Tags

• _at_param ltname of parametergt short description of
  parameter
• Describe the named parameter to this method
• Skip this tag if the method has no parameters
• Used in Method
• E.g. _at_param size number of elements in the array
• _at_return text
• Describe the value returned by this method
• Skip this tag if the method has no return value
• Appears after _at_param tag(s)
• Used in Method

13
Example

• /
• Validates a chess move.
• _at_author John Doofus
• _at_param theFromLoc Location of piece being moved
  
• _at_param theRank Rank of piece being moved
• _at_param theToLoc Location of destination square
• _at_return true if a valid chess move or false if
  invalid /
• boolean isValidMove(int theFromLoc, int theRank,
  int theToLoc) ...

14
JavaDoc Tags

• _at_throws ltname of exceptiongt description of
  circumstances under which exception is thrown
• Describes the named checked (or explicit
  unchecked) exception that can be thrown by this
  method
• Skip this tag if the method throws no checked (or
  explicit unchecked) exceptions
• Should follow _at_param and _at_return tags
• If method throws more than one exception
• they should appear in alphabetical order by
  exception name 
• Used in
• Method 
• _at_throws FileNotFoundException raised if the user
  does not specify a valid file name

15
Checked vs. Unchecked

• You only advertise (via throws on method header)
  (or catch) and include _at_throws for
• (P.S. throws on method header ? exception is not
  handled in the method but forwarded to the
  invoker)
• checked exceptions
• explicitly thrown unchecked ones
• Unchecked exceptions
• beyond your control (Error) or result from a
  condition that you should not have allowed in the
  first place (RuntimeException)
• are subclasses of
• RuntimeException (e.g. ArrayIndexOutOfBoundExcepti
  on)
• Error (e.g. OutOfMemoryError)
• The Java compiler checks all exception handling,
  except exceptions represented by (subclasses of)
  Error and RuntimeException

16
Checked vs. Unchecked

• Checked exceptions
• represent invalid conditions in areas outside the
  immediate control of the program
• E.g. database problems, network outages, or
  absent files
• are subclasses of Exception (except
  RuntimeException)
• the compiler will confirm at compile time that
  the method includes code that might throw an
  exception
• must be caught or forwarded (advertised)
• This can be done in a try ... catch statement or
  by defining the exception in the method
  definition (via throws)

17
Class Hierarchy

• http//java.sun.com/j2se/1.4.2/docs/api/java/lang
  /Throwable.html
• java.lang.Object      --java.lang.Throwable  
                  --java.lang.Exception        
                     --java.lang.ClassNotFoundE
  xception                           
  --java.io.IOException                  
                     --java.io.FileNotFoundExce
  ption                           
  --java.lang.RuntimeException        
                                
  --java.lang.NullPointerException        
             --java.lang.ArithmeticException
•                      --java.lang.IllegalAr
  gumentException                    
  --java.lang.IndexOutOfBoundsException        
                                            
  --java.lang.ArrayIndexOutOfBoundsException      
              --java.lang.Error              
                 --java.lang.VirtualMachineError
                                           
  --java.lang.OutOfMemoryError

18
Example

• /
• Change the contents of a text file in its
  entirety,
• overwriting any existing text.
• _at_param aFile is an existing file (not a
  directory) which can
• be written.
• _at_param aContents is the text to be placed into
  aFile.
• _at_throws FileNotFoundException if aFile does not
  exist.
• _at_throws IOException if stream to aFile cannot
  be written
• to or closed.
• _at_throws IllegalArgumentException if aFile is a
  directory.
• _at_throws IllegalArgumentException if aFile
  cannot be
• written.
• _at_throws NullPointerException if aFile is null.
• _at_throws NullPointerException if aContents is
  null.
• /
• static public void setContents(File aFile, String
  aContents) throws FileNotFoundException,
  IllegalArgumentException, NullPointerException

19
Example

• if (aFile null)
• throw new NullPointerException("File must not be
  null.")
• if (aContents null)
• throw new NullPointerException("Contents must
  not be null.")
• if (!aFile.exists())
• throw new FileNotFoundException("File does not
  exist" aFile)
• if (!aFile.isFile())
• throw new IllegalArgumentException("Must not be
  a directory" aFile)
• if (!aFile.canWrite())
• throw new IllegalArgumentException("File cannot
  be written" aFile)
• Writer output null
• try //use buffering
• output new BufferedWriter( new
  FileWriter(aFile) ) //IO Exception
• output.write( aContents )
• catch(IO Exception e)
• System.out.println(e.PrintStackTrace()
• finally //flush and close both "output" and its
  underlying FileWriter

20
Tag summary

• http//java.sun.com/j2se/1.3/docs/tooldocs/win32/j
  avadoc.html
• http//java.sun.com/j2se/javadoc/writingdoccomment
  s/

21
Minimum Requirements

• Class (or package)
• _at_author
• _at_version
• _at_since
• _at_see
• _at_deprecated
• Field
• _at_see
• _at_deprecated (followed by another _at_see sometimes)

• Method/Constructor
• _at_author (only in case method is written by
  another author)
• ltorderedgt
• _at_param
• _at_return
• _at_throws
• lt/orderedgt
• _at_see
• _at_deprecated (followed by another _at_see sometimes)

22
Example http//csis.pace.edu/bergin/patterns/jav
adoc.html

• package jb
• import java.util.NoSuchElementException
• import java.util.ArrayList
• /
• The Stack class represents a last-in-first-out
  stack of objects.
• _at_author Joseph Bergin
• _at_version 1.0
• _at_since May 2000
• /
• public class Stack
• /
• Pushes an item on to the top of this stack.
• _at_param item the item to be pushed.
• /
• public void push(Object item)this.elements.add(it
  em)

23
Example

• /
• Removes the object at the top of this stack and
  
• returns that object.
• _at_return The object at the top of this stack.
• _at_throws NoSuchElementException if stack is
• empty.
• /
• public Object pop() throws NoSuchElementException
  
• int length this.elements.size()
• if (length 0)
• throw new NoSuchElementException()
• return this.elements.remove(length - 1)

24
Example

• /
• Tests if this stack is empty.
• _at_return true if this stack is empty and
• false otherwise.
• /
• public boolean isEmpty()
• return this.elements.isEmpty()
• private ArrayList elements new ArrayList()

25
Running JavaDoc

• javadoc options packages filesnames
• Can list one or packages
• No wildcards (i.e. )
• Can list one or more java files
• Can use wildcards

26
javadoc Command-line Options

• -public
• Only public classes, members and methods are
  documented
• For API users
• -protected
• Public and protected
• Most common (default)
• -package
• Public, protected and package
• -private
• All
• For internal use

• -version
• Causes the _at_version tag to be included in the
  documentation
• -d directory
• Location of output HTML documentation
• Same directory as source by default
• -author
• Causes the _at_author tag to be included in the
  documentation
• -nodeprecated
• Deprecated methods and classes wont be documented

27
Result Documentation

• Class Stack
• javadoc .java
• javadoc version author private -nodeprecated
  .java

28
JavaDoc using Eclipse

• Code formatter
• Highlight code
• Source gt Format
• JavaDoc comment generator
• Select the project or file in Package Explorer
• Project gt Generate Javadoc
• Follow wizard

29
Example

• public class ManageFile
• private String file
• public ManageFile(String FileName)
• this.file FileName
• public String getFile()
• return file
• public void setFile(String FileName)
• this.file FileName
• public void displayFile() throws
  FileNotFoundException, IOException
• //code to open file and display its contents on
  screen