JavaDoc-Java Programming-Lecture Slides, Slides of Java Programming

Download JavaDoc-Java Programming-Lecture Slides and more Slides Java Programming in PDF only on Docsity!

JavaDoc

COMP 302

JavaDoc

 javadoc: The program to generate java code

documentation.

 Input: Java source files (.java)

 Individual source files

 Root directory of the source files

 Output: HTML files documenting specification

of java code

 One file for each class defined  Package and overview files

Placement of comments

 All comments are placed immediately before

class, interface, constructor, method, or field declarations. No other stuff between them are not permitted.

/**

• This is the class comment for the class Whatever. */

import com.sun; // MISTAKE

public class Whatever {}

Structure of the specification

Main Description

Tag Section

Comments are written in HTML

/**

• This is a doc comment.

• @see java.lang.Object

*/

Note that tag names are case-sensitive. @See

is a mistaken usage - @see is correct.

First sentence for summary

 The first sentence of each doc comment

should be a summary sentence, containing a concise but complete description of the declared entity.

 This sentence ends at the first period that is

followed by a blank, tab, or line terminator, or at the first block tag.

 The Javadoc tool copies this first sentence to

the member summary at the top of the HTML page.

Automatic copying of method comments

 When a main description, or @return, @param or @throws tag is missing from a method comment, the Javadoc tool copies the corresponding main description or tag comment from the method it overrides or implements (if any.

 For example, when a @param tag for a particular parameter is missing, then the comment for that parameter is copied from the method further up the inheritance hierarchy.

 When a @throws tag for a particular exception is missing, the @throws tag is copied only if that exception is declared.

Explicitly inherit comment with

{@inheritDoc} tag

 Insert the inline tag {@inheritDoc} in a method main

description or @return, @param or @throws tag comment - the corresponding inherited main description or tag comment is copied into that spot.

/**

• Draws its shape on the screen
• @param {@inheritDoc}
• @return {@inheritDoc} */

public boolean drawShape(Screen screen){...}

Main description

 The section that introduces the class, method

of field. It comes first in the specification before the tag section.

 The first sentence of each doc comment

should be a summary sentence, containing a concise but complete description of the declared entity. It will be placed in package overview and class overview.

@param parameter-name description

 Adds a parameter to the "Parameters" section.

The description may be continued on the next line. This tag is valid only in a doc comment for a method or constructor.

**/****

*** Tests a character and notifies an observer

• according to the value of the character
• @param ch the character to be tested
• @param obs the observer to be notified /*

public void testCharacter( char ch , Observer obs )

@see reference

 Adds a "See Also" heading with a link or text entry that points to reference. A doc comment may contain any number of @see tags, which are all grouped under the same heading.  The @see tag has three variations:  @see string  Adds a text entry for string. No link is generated.  @see "The Java Programming Language"  @see label  Adds a link as defined by URL#value. The URL#value is a relative or absolute URL. The Javadoc tool distinguishes this from other cases by looking for a less-than symbol (<) as the first character.  @see Java Spec  @see package.class # member label  Adds a link, with visible text label , that points to the documentation for the specified name in the Java Language that is referenced.  @see String#equals(Object) equals (generates a link to String.equals())  See Also: equals

 @see java.lang.String // String  @see java.lang.String The String class // The String class

 @see String // String  @see String#equals(Object) // String.equals(Object)

 @see String#equals // String.equals(java.lang.Object)  @see java.lang.Object#wait(long) // java.lang.Object.wait(long)

 @see Character#MAX_RADIX // Character.MAX_RADIX  @see Java Spec // Java Spec  @see "The Java Programming Language" // "The Java Programming Language"

{@link package.class # member label }

 Here is a comment that refers to the

getComponentAt(int, int) method: **/****

*** Use the {@link #getComponentAt(int, int)

• getComponentAt} method. /*

 From this, the standard doclet would generate the

following HTML:

Use the getComponentAt method.

 Which appears on the web page as:

Use the getComponentAt method.

@deprecated deprecated-text

 Adds a comment indicating that this API should no longer be used (even though it may continue to work). The Javadoc tool moves the deprecated-text ahead of the main description, placing it in italics and preceding it with a bold warning: "Deprecated".

 This tag is valid in all doc comments: overview, package, class, interface, constructor, method and field.

/**

• @deprecated As of JDK 1.1, replaced by
• {@link #setBounds(int,int,int,int)} */