1. Documentation Dr. Andrew Wallace PhD BEng(hons) EurIng andrew@cs.umu.se

2. Overview Documentation Javadoc More documentation

3. Documentation Document your program For others For yourself Programs change over time Different people can work on it

4. 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?

5. Documentation Comments in the code // /* … */ Comments blocks of code Comments methods Comment class Comment package

6. Quiz Why should you document your code?

7. 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

8. 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

9. Javadoc @param – add information on parameters passed to a method @return – information on the return value @throws – throw by the method and why

10. 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 {

11. 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

12. Quiz What is Javadoc? How do you use it?

13. More documentation What to document? How to use the code System description Algorithm description Limits Testing

14. More documentation Using the code Give example Compilation Anything special needed? Some large projects can become complex

15. 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

16. 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?

17. More documentation Solution limitations Limits under test Limits that effect specification Nothing is perfect! How can the limits be avoided?

18. 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?

19. More documentation Coding standards Indentations Layout of loops Brackets Line length

20. Quiz Name three other types of documents (other than source code)? What do you document in each?

21. Questions?