Survey
* Your assessment is very important for improving the workof artificial intelligence, which forms the content of this project
Download Program documentation
Document related concepts
no text concepts found
Transcript
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
