1 Mobile IP, or TCP/IP on tour Distribuerade system, VT2000 [email protected].
Documentation Dr. Andrew Wallace PhD BEng(hons) EurIng [email protected].
-
Upload
helen-hubbard -
Category
Documents
-
view
218 -
download
1
Transcript of Documentation Dr. Andrew Wallace PhD BEng(hons) EurIng [email protected].
![Page 2: Documentation Dr. Andrew Wallace PhD BEng(hons) EurIng andrew@cs.umu.se.](https://reader038.fdocuments.in/reader038/viewer/2022103100/56649f295503460f94c4253f/html5/thumbnails/2.jpg)
Overview
• Documentation
• Javadoc
• More documentation
![Page 3: Documentation Dr. Andrew Wallace PhD BEng(hons) EurIng andrew@cs.umu.se.](https://reader038.fdocuments.in/reader038/viewer/2022103100/56649f295503460f94c4253f/html5/thumbnails/3.jpg)
Documentation
• Document your program• For others• For yourself
• Programs change over time• Different people can work on it
![Page 4: Documentation Dr. Andrew Wallace PhD BEng(hons) EurIng andrew@cs.umu.se.](https://reader038.fdocuments.in/reader038/viewer/2022103100/56649f295503460f94c4253f/html5/thumbnails/4.jpg)
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?
![Page 5: Documentation Dr. Andrew Wallace PhD BEng(hons) EurIng andrew@cs.umu.se.](https://reader038.fdocuments.in/reader038/viewer/2022103100/56649f295503460f94c4253f/html5/thumbnails/5.jpg)
Documentation
• Comments in the code• //• /* … */
• Comments blocks of code
• Comments methods
• Comment class
• Comment package
![Page 6: Documentation Dr. Andrew Wallace PhD BEng(hons) EurIng andrew@cs.umu.se.](https://reader038.fdocuments.in/reader038/viewer/2022103100/56649f295503460f94c4253f/html5/thumbnails/6.jpg)
Quiz
• Why should you document your code?
![Page 7: Documentation Dr. Andrew Wallace PhD BEng(hons) EurIng andrew@cs.umu.se.](https://reader038.fdocuments.in/reader038/viewer/2022103100/56649f295503460f94c4253f/html5/thumbnails/7.jpg)
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
![Page 8: Documentation Dr. Andrew Wallace PhD BEng(hons) EurIng andrew@cs.umu.se.](https://reader038.fdocuments.in/reader038/viewer/2022103100/56649f295503460f94c4253f/html5/thumbnails/8.jpg)
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>
![Page 9: Documentation Dr. Andrew Wallace PhD BEng(hons) EurIng andrew@cs.umu.se.](https://reader038.fdocuments.in/reader038/viewer/2022103100/56649f295503460f94c4253f/html5/thumbnails/9.jpg)
Javadoc
• @param – add information on parameters passed to a method
• @return – information on the return value
• @throws – throw by the method and why
![Page 10: Documentation Dr. Andrew Wallace PhD BEng(hons) EurIng andrew@cs.umu.se.](https://reader038.fdocuments.in/reader038/viewer/2022103100/56649f295503460f94c4253f/html5/thumbnails/10.jpg)
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
{
![Page 11: Documentation Dr. Andrew Wallace PhD BEng(hons) EurIng andrew@cs.umu.se.](https://reader038.fdocuments.in/reader038/viewer/2022103100/56649f295503460f94c4253f/html5/thumbnails/11.jpg)
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
![Page 12: Documentation Dr. Andrew Wallace PhD BEng(hons) EurIng andrew@cs.umu.se.](https://reader038.fdocuments.in/reader038/viewer/2022103100/56649f295503460f94c4253f/html5/thumbnails/12.jpg)
Quiz
• What is Javadoc?
• How do you use it?
![Page 13: Documentation Dr. Andrew Wallace PhD BEng(hons) EurIng andrew@cs.umu.se.](https://reader038.fdocuments.in/reader038/viewer/2022103100/56649f295503460f94c4253f/html5/thumbnails/13.jpg)
More documentation
• What to document?
• How to use the code
• System description
• Algorithm description
• Limits
• Testing
![Page 14: Documentation Dr. Andrew Wallace PhD BEng(hons) EurIng andrew@cs.umu.se.](https://reader038.fdocuments.in/reader038/viewer/2022103100/56649f295503460f94c4253f/html5/thumbnails/14.jpg)
More documentation
• Using the code
• Give example
• Compilation• Anything special needed?
• Some large projects can become complex
![Page 15: Documentation Dr. Andrew Wallace PhD BEng(hons) EurIng andrew@cs.umu.se.](https://reader038.fdocuments.in/reader038/viewer/2022103100/56649f295503460f94c4253f/html5/thumbnails/15.jpg)
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
![Page 16: Documentation Dr. Andrew Wallace PhD BEng(hons) EurIng andrew@cs.umu.se.](https://reader038.fdocuments.in/reader038/viewer/2022103100/56649f295503460f94c4253f/html5/thumbnails/16.jpg)
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?
![Page 17: Documentation Dr. Andrew Wallace PhD BEng(hons) EurIng andrew@cs.umu.se.](https://reader038.fdocuments.in/reader038/viewer/2022103100/56649f295503460f94c4253f/html5/thumbnails/17.jpg)
More documentation
• Solution limitations
• Limits under test
• Limits that effect specification
• Nothing is perfect!
• How can the limits be avoided?
![Page 18: Documentation Dr. Andrew Wallace PhD BEng(hons) EurIng andrew@cs.umu.se.](https://reader038.fdocuments.in/reader038/viewer/2022103100/56649f295503460f94c4253f/html5/thumbnails/18.jpg)
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?
![Page 19: Documentation Dr. Andrew Wallace PhD BEng(hons) EurIng andrew@cs.umu.se.](https://reader038.fdocuments.in/reader038/viewer/2022103100/56649f295503460f94c4253f/html5/thumbnails/19.jpg)
More documentation
• Coding standards
• Indentations
• Layout of loops
• Brackets
• Line length
![Page 20: Documentation Dr. Andrew Wallace PhD BEng(hons) EurIng andrew@cs.umu.se.](https://reader038.fdocuments.in/reader038/viewer/2022103100/56649f295503460f94c4253f/html5/thumbnails/20.jpg)
Quiz
• Name three other types of documents (other than source code)?
• What do you document in each?
![Page 21: Documentation Dr. Andrew Wallace PhD BEng(hons) EurIng andrew@cs.umu.se.](https://reader038.fdocuments.in/reader038/viewer/2022103100/56649f295503460f94c4253f/html5/thumbnails/21.jpg)
Questions?