Documentation Dr. Andrew Wallace PhD BEng(hons) EurIng

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 to add specific details Can use HTML tags as well like

– add information on parameters passed to a – information on the return – 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 address – a reference to a class containing the address information need to create a connection. The method assumes this is not – 0 = all test ok, else a number indicates which test – IOException if there is a problem establishing a connection. The exception contains further information on the problem. */ Public int TestIO(Adress adress) thows IOException {

– the original person who wrote the code. At class or interface – version information in case various version of the software – 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?