DocumentationDr. Andrew Wallace PhD BEng(hons) EurIng

andrew@cs.umu.se

Overview

• Documentation

• Javadoc

• More documentation

Documentation

• Document your program• For others• For yourself

• Programs change over time• Different people can work on it

Documentation

• What is this?

• What does it do?• How does it fit in with everything else?

• How do I use it?

• What are the inputs and outputs?

• What assumptions are made?

Documentation

• Comments in the code• //• /* … */

• Comments blocks of code

• Comments methods

• Comment class

• Comment package

Quiz

• Why should you document your code?

Javadoc

• Javadoc is a program for generating documentation form the code• Saves having to view the code

• Uses special comments in the code

• Javadoc integrated into Eclipse• You need JDK• Project->generate javadoc

• Write the comments within the class file, as method declarations and for the class attributes

• Outputs HTML files

Javadoc

• Start a Javadoc comment with /** and end with */

• Write a block describing the class etc.

• Use keywords that start with @ to add specific details

• Can use HTML tags as well like <h1> </h1>

Javadoc

• @param – add information on parameters passed to a method

• @return – information on the return value

• @throws – throw by the method and why

Javadoc

/**

This method test IO by calling various IO methods. The method will loop until all test are completed or an error occurs. This method can be used to check a commination link.

@param address – a reference to a class containing the address information need to create a connection. The method assumes this is not null.

@return – 0 = all test ok, else a number indicates which test failed.

@throws – IOException if there is a problem establishing a connection. The exception contains further information on the problem.

*/

Public int TestIO(Adress adress) thows IOException

{

Javadoc

• @author – the original person who wrote the code. At class or interface level

• @version – version information in case various version of the software exists.

• @see – information on where to find additional information or information on related code

Quiz

• What is Javadoc?

• How do you use it?

More documentation

• What to document?

• How to use the code

• System description

• Algorithm description

• Limits

• Testing

More documentation

• Using the code

• Give example

• Compilation• Anything special needed?

• Some large projects can become complex

More documentation

• System description • Internal, how it is built up

• How do the classes fit in?• Context

• References to more information • Javadoc documents

• Diagrams• UML

More documentation

• Algorithm descriptions

• Write up how more complex algorithms works such as sorting

• Described independent of the code

• How was a complex problem solved?

More documentation

• Solution limitations

• Limits under test

• Limits that effect specification

• Nothing is perfect!

• How can the limits be avoided?

More documentation

• Test documentation

• How to test the code?• Specifications• What can go wrong?

• Comment each test case• Why?• Results?

• Test plan• When to test?

More documentation

• Coding standards

• Indentations

• Layout of loops

• Brackets

• Line length

Quiz

• Name three other types of documents (other than source code)?

• What do you document in each?

Questions?