1. How do you identify a comment so the Javadoc tool will recognize it? 2. What
ID: 3660269 • Letter: 1
Question
1. How do you identify a comment so the Javadoc tool will recognize it? 2. What should a comment at the class level contain? 3. What is a tag and how are they used in Javadoc comments? Give an example of using tags in your answer. 4. What type of information should be included in a method level comment? 5. How do you provide a link from one class to a related class? 6. What type of output does the javadoc command generate and how do you view the output? 7. What is a Java archive? 8. What command is used to create a Java archive? Explain using an example. 9. What are the steps necessary to create a JAR file where the main entry point is identified? 10. What command is used to execute a JAR file which has a main entry point?Explanation / Answer
1. The Javadoc tool parses the declarations and documentation comments in a set of Java source files and produces a corresponding set of HTML pages describing (by default) the public and protected classes, nested classes (but not anonymous inner classes), interfaces, constructors, methods, and fields. You can use it to generate the API (Application Programming Interface) documentation or the implementation documentation for a set of source files.
You can run the Javadoc tool on entire packages, individual source files, or both. When documenting entire packages, you can either use -subpackages for traversing recursively down from a top-level directory, or pass in an explicit list of package names. When documenting individual source files, you pass in a list of source (.java) filenames. Examples are given at the end of this document. How Javadoc processes source files is covered next.
2. Overview Comment File
Each application or set of packages that you are documenting can have its own overview documentation comment, kept in its own "source" file, that the Javadoc tool will merge into the overview page that it generates. You typically include in this comment any documentation that applies to the entire application or set of packages.
To create an overview comment file, you can name the file anything you want, typically overview.html and place it anywhere, typically at the top level of the source tree. Notice you can have multiple overview comment files for the same set of source files, in case you want to run javadoc multiple times on different sets of packages. For example, if the source files for the java.applet package are contained in /home/user/src/java/applet directory, you could create an overview comment file at /home/user/src/overview.html.
The doc comments for the Java platform API specification is owned programmers. However, they are edited by both programmers and writers. It is a basic premise that writers and programmers honor each other's capabilities and both contribute to the best doc comments possible. Often it is a matter of negotiation to determine who writes which parts of the documentation, based on knowledge, time, resources, interest, API complexity, and on the state of the implementation itself. But the final comments must be approved by the responsible engineer.
3. JAVADOC TAGS
The Javadoc tool parses special tags when they are embedded within a Java doc comment. These doc tags enable you to autogenerate a complete, well-formatted API from your source code. The tags start with an "at" sign (@) and are case-sensitive -- they must be typed with the uppercase and lowercase letters as shown. A tag must start at the beginning of a line (after any leading spaces and an optional asterisk) or it is treated as normal text. By convention, tags with the same name are grouped together. For example, put all @see tags together.
Tags come in two types:
4. I've been pruning unnecessary comments as I refactor and I've noticed our code has painfully obvious descriptions of methods.
Most of the "documented" functions are just method names used by convention in our MVC framework (CakePHP). It's inherently obvious that the save method in the Production Controller performs the necessary actions to save Production Information.
We don't actually use Java Doc and I question the value of these descriptions even if they were included in Java Doc style documentation. The only reason I haven't touched these because they're method documentation that's supposed to be valuable. The method documentation also hasn't been used consistently, about half of our Controller/model methods are documented.
Is there any reason to keep these obvious "Java Doc" comments or should I prune them in favor of "self documenting code" and only make Java Doc comments for less obvious methods?
5. How to create a hyperlink to another page. It's a set tag format that's part of the Hyper Text Markup Language (HTML) like any of the others you may have seen. Once you learn the format, you can make as many links as you want to any other page you want.
Now an example: The code below would create a link to the HTMLGoodies home page.
Related Questions
Navigate
Integrity-first tutoring: explanations and feedback only — we do not complete graded work. Learn more.