Survey
* Your assessment is very important for improving the workof artificial intelligence, which forms the content of this project
* Your assessment is very important for improving the workof artificial intelligence, which forms the content of this project
Program documentation Using the Javadoc tool Program documentation using the Javadoc tool 1 JavaDoc • J2SE comes with a tool to extract comments from Java source code to produce program documentation in HTML format. • Doc comments – /** ….*/ – Written immediately before the programming part to document. • Ordinary comments – /* …*/ – // – Not used in program documentation. Program documentation using the Javadoc tool 2 Doc comments • Plain text – Be careful with HTML tags • A < B must be written A < B • HTML – The HTML you write in the JavaDoc comments will be inserted into the generated HTML files. – Don’t use tags like <html>, <head>, <body> etc. • These tags are generated by the Javadoc tool. • Special tags (not HTML, but doc tags) – @author – @since version number – @deprecated • The compiler issues a warning if you use classes or methods tagged @deprecated. – {@code text} • Wrapped in <code>…</code> HTML tags • For program examples, etc. Program documentation using the Javadoc tool 3 What to document? • All public and protected parts of a program should be documented using JavaDoc comments – Package-protected and private parts are not that important to document since they are only for internal use. • Classes – Write JavaDoc comment in front of the class declaration. • Methods – Parameters to the method • @param – Return values • @return – Exceptions thrown from the method • @throws • Checked exceptions • Runtime exceptions that the caller might reasonably want to catch. Program documentation using the Javadoc tool 4 Documenting methods • Document the contract between the method and it callers – Focus on what the method does, not how – Preconditions – Postconditions – Side effects – Thread safety Program documentation using the Javadoc tool 5 Generating HTML files • Command line – Javadoc file.java • Generate HTML files for a single Java file – Javadoc *.java • Generate HTML files for all Java files (in the current directory) – Javadoc –author file.java • Include @author information in HTML files – Javadoc –private file.java • Generate HTML files for private parts of the program. – Lots of other options. Program documentation using the Javadoc tool 6 Style • Look at the HTML files of the existing class library in J2SE. • Use the HTML tag <code> for code examples, keywords, class names, methods names, etc. • Use 3rd person, not 2nd person – Gets the label – Get the label (right) (wrong) Program documentation using the Javadoc tool 7 NetBeans assistance • NetBeans can help you write JavaDoc comments in your Java files – You have to write the comments yourself, but NetBeans points out where you ought to write comments. • NetBeans can active the JavaDoc program to generate the HTML pages. Program documentation using the Javadoc tool 8 Technical writers vs. programmers • Programmers are supposed to write the program code and the doc comments. • Programmers are usually better at writing code than comments. • Some companies employee technical writers who write program documentation – Doc comments • Both programmer and technical writer need write access to the program files. – Reference documentation – User manuals – Tutorials Program documentation using the Javadoc tool 9 References • Sun Microsystems Java Doc Tool Homepage – • Sun Microsystems How to Write Doc Comments for the Javadoc Tool – – • http://java.sun.com/j2se/javadoc/writing doccomments/index.html Sun’s internal standards for writing doc comments. Arnold et al. The Java Programming Language 4th edition, Addison Wesley 2006 – – • http://java.sun.com/j2se/javadoc/index.j sp Chapter 19 Documentation Comments, page 481-498 Introduction with emphasis on JavaDoc tags. Joshua Bloch Effective Java, Addison Wesley 2001 – Item 28: Write doc comments for all exposed API elements, page 136-139 Program documentation using the Javadoc tool 10