1 / 10

Program documentation

Program documentation. Using the Javadoc tool. 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 /* …*/ //

kirk-padilla
Download Presentation

Program documentation

An Image/Link below is provided (as is) to download presentation Download Policy: Content on the Website is provided to you AS IS for your information and personal use and may not be sold / licensed / shared on other websites without getting consent from its author. Content is provided to you AS IS for your information and personal use only. Download presentation by click this link. While downloading, if for some reason you are not able to download a presentation, the publisher may have deleted the file from their server. During download, if you can't get a presentation, the file might be deleted by the publisher.

E N D

Presentation Transcript

  1. Program documentation Using the Javadoc tool Program documentation using the Javadoc tool

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

  3. Doc comments • Plain text • Be careful with HTML tags • 1 < B must be written A &lt; B lt ~ less than • Salary > 0 must be written salary &gt; 0 gt ~ greater than • 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

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

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

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

  7. Style • Look at the HTML files of the existing class library in J2SE. • Use the JavaDoc tag {@code parameter} for code examples, keywords, class names, methods names, etc. • Use 3rd person, not 2nd person • Gets the label (right) • Get the label (wrong) Program documentation using the Javadoc tool

  8. NetBeans assistance • NetBeans can help you write JavaDoc comments in your Java files • NetBeans can activate the JavaDoc program to generate the HTML pages. Program documentation using the Javadoc tool

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

  10. References • Sun Microsystems Java Doc Tool Homepage • http://java.sun.com/j2se/javadoc/index.jsp • Sun Microsystems How to Write Doc Comments for the Javadoc Tool • http://java.sun.com/j2se/javadoc/writingdoccomments/index.html • Sun’s internal standards for writing doc comments. • Arnold et al.The Java Programming Language 4th edition, Addison Wesley 2006 • Chapter 19 Documentation Comments, page 481-498 • Introduction with emphasis on JavaDoc tags. • Joshua BlochEffective Java, Addison Wesley 2001 • Item 28: Write doc comments for all exposed API elements, page 136-139 Program documentation using the Javadoc tool

More Related