Javadoc short tutorial

Size: px

Start display at page:

Download "Javadoc short tutorial"

Alvin Briggs
6 years ago
Views:

Javadoc short tutorial General Javadoc processes doc-comments. A doc-comment differs from other type of comments (i.e. double slash //) in that it begins with (a slash followed by a double asterisks) and ends with.

1 Javadoc short tutorial General Javadoc processes doc-comments. A doc-comment differs from other type of comments (i.e. double slash //) in that it begins with (a slash followed by a double asterisks) and ends with. Each body line begins with a single asterisk *. * This is a doccomment Eugene Teng As seen in the above example, doc-comments may contain HTML tags. When javadoc parses a doc-comment, leading asterisk, blanks and tabs preceding the initial asterisk character are discarded. The first sentence of each doc comment will also be the summary sentence that appears in the summary section of the.html file. There are two sections in a doc-comment. The first section is called main description. The main description begins after the starting delimiter and continues until the first tag (to be explained later). The second section is called tag section which starts with the first block tag. It is possible to have a doc-comment with only a tag section and no main description. The main description cannot continue after the tag section begins. Javadoc uses tags to distinguish blocks and generate appropriate HTML style for each tag. From programmer s perspective, tags enable us to format our documents. Tags come in two types: 1. Block tags - Can be placed only in the tag section that follows the main description. Block tags are of the 2. Inline tags - Can be placed anywhere in the main description or in the comments for block tags. Inline tags are denoted by curly braces: {@tag_name} For a complete list of tags, please visit: doctags

2 Source type The Javadoc tool generates documentations for 4 types of "sources". 1. Java class source files (.java) 2. Package comment 3. Overview comment 4. Miscellaneous unprocessed files Example: WebSiteCore.java class description 1. Java source files * This is a summary sentence. * The WebSiteCore class contains functions for: * <ul> * <li> Querying database to obtain user trip information * <li> Retrieving user s friend list * <li> Cleaning data * </ul> * * Notice that the %I% and %G% in the version tag are custom defined variables. * They are recognized by version control system (like tortoisesvn). * That is, CVS software will automatically replace and update version # * Kenny Wu Danny Ho %I%, %G% public class WebSiteCore { Output: WebSiteCore.html

Example: getuserfriendauthtrip function signiture * This method gets friend's trip information. * This method first registers PostgreSQL driver by loading driver class (running static block).

3 Example: getuserfriendauthtrip function signiture * This method gets friend's trip information. * This method first registers PostgreSQL driver by loading driver class (running static block). * It then utilizes conneciton manager to connect to PostgreSQL server. userid A string argument used to indicate user's ID friendid A string argument used to indicate the ID of user's friend none This method does not throw anything String This method returns a string that embeds trip information. The result is to be parsed. Kenny Wu Danny Ho %I%, %G% public static String getuserfriendauthtrip(string userid, String friendid){ Output: WebSiteCore.html method summary WebSiteCore.html method detail

4 2. Package comment There are two ways to write package comment. The first way is to write normal doc-comment and save it in a file named package-info.java (Note: the whole name must match for Javadoc to create package comment). The second way is to create package comment html named package.html. Javadoc will retrieve contents within <body> tags. If package-info.java is present, Javadoc will ignore package.html. The location of these files must be in the package directory where the.java files reside. Example: package-info.java * Everything * before * the first sentence (delimited by a period) will appear in the package summary (note this period->). * The plash package provides functions for: * 1. Help establish database connection. * 2. Facilitate database queries. (a is inserted here) * * As illustrated above, a new line in Javadoc comment does not start a new line. * A br tag is needed to dictate a carriage return. * * Test link {@link plash.jsontest test} here * 1.1 <a href = "tinyurl.com/page_of_javaawt" > java.awt </a> Eugene Teng package plash; Output: index.html Notice the difference tag and tag. We supply a full class name tag and Javadoc will automatically find the path to link to. tag we need to include an HTML anchor tag for the link to work. 3. Overview comment. An overview comment will be extracted from a programmer-defined HTML. You can name this HTML anything and place it anywhere you want. For example, plash-overview.html located at the top level of the source tree. Notice that by default only contents within <body> and </body> tags are processed.

5 4. Miscellaneous unprocessed files Include various kinds of files. For example, graphic files, example Java source (.java) and class (.class) files, and self-standing HTML files whose content would otherwise overwhelm the documentation comment of a normal Java source file when included there. This type of source is not utilized in our project at this moment. For more information, please refer to the following URL: essed Generating a Java document 1. In Eclipse, go to Project menu item and then select Generate Javadoc Or Right click on the project and select Export... Then select Javadoc, and click Next You will be brought to a window: 2. For the first use, click Configure to locate javadoc.exe. It usually resides in the bin folder of your JDK installation. 3. Select the packages or sources you want. 4. Select destination folder and then click Next. 5. Select the options and tags you want to enable. The default is to enable all options and tags. 6. You can also generate links that link to documentations of the libraries you have used. 7. Click Next and there you can include your overview description HTML. Remember that only contents inside body tags are included. 8. Click Finish.

Javadocing in Netbeans (rev )

Javadocing in Netbeans (rev ) Javadocing in Netbeans (rev. 2011-05-20) This note describes how to embed HTML-style graphics within your Javadocs, if you are using Netbeans. Additionally, I provide a few hints for package level and