Java Docs
Download as PPTX, PDF0 likes1,779 views
Javadoc is a standard way to document Java code using special comment formats that include class-level and member-level comments, which help describe classes and their members. It utilizes specific tags such as @param, @return, and @throws to detail method parameters, return values, and exceptions. The document also provides examples of how to implement javadoc comments effectively, emphasizing the importance of thorough documentation for user-friendly code.
![import java.io.*;
/**
* <h1>Add Two Numbers!</h1>
* The AddNum program implements an application that
* simply adds two given integer numbers and Prints
* the output on the screen.
* <p>
* <b>Note:</b> Giving proper comments in your program makes it more
* user friendly and it is assumed as a high quality code. *
* @author Zara Ali * @version 1.0 * @since 2014-03-31
*/ public class AddNum {
/** * This method is used to add two integers. This is
* a the simplest form of a class method, just to
* show the usage of various javadoc Tags.
* @param numA This is the first paramter to addNum method
* @param numB This is the second parameter to addNum method
* @return int This returns sum of numA and numB.
*/
public int addNum(int numA, int numB) {
return numA + numB;
} /** * This is the main method which makes use of addNum method. * @param args Unused. *
@return Nothing. * @exception IOException On input error. * @see IOException */ public
static void main(String args[]) throws IOException { AddNum obj = new AddNum(); int
sum = obj.addNum(10, 20); System.out.println("Sum of 10 and 20 is :" + sum); } }](https://image.slidesharecdn.com/softwaredocumentation-150826063553-lva1-app6891/85/Java-Docs-10-320.jpg)
Java Docs
- 1. JavaDoc
- 2. Javadoc Javadoc is a convenient, standard way to document your Java code. Javadoc is actually a special format of comments. There are two kinds of Javadoc comments: class-level comments: Class-level comments provide the description of the classes and member-level comments: member-level comments describe the purposes of the members. Both types of comments start with /** and end with */. For example, this is a Javadoc comment: /** This is a Javadoc comment */
- 3. Structure of a Javadoc comment A Javadoc comment is set off from code by standard multi-line comment tags /* and */. The opening tag (called begin-comment delimiter), has an extra asterisk, as in /**. The first paragraph is a description of the method documented. Following the description are a varying number of descriptive tags, signifying: The parameters of the method (@param) What the method returns (@return) Any exceptions the method may throw (@throws) Other less-common tags such as @see (a "see also" tag)
- 4. Overview of Javadoc The basic structure of writing document comments is to embed them inside /** ... */. The Javadoc is written next to the items without any separating newline. Note that any import statements must precede the class declaration. The class declaration usually contains: // import statements /** * @author Firstname Lastname <address @ example.com> * @version 1.6 (current version number of program) * @since 2010-03-31 (the version of the package this class was first added to) */ public class Test { // class body}
- 5. Javadoc tags Tag & Parameter Usage Applies to Since @author John Smith Describes an author. Class, Interface, Enum @version version Provides software version entry. Max one per Class or Interface. Class, Interface, Enum @since since-text Describes when this functionality has first existed. Class, Interface, Enum, Field, Method @see reference Provides a link to other element of documentation. Class, Interface, Enum, Field, Method @param name description Describes a method parameter. Method @return description Describes the return value. Method
- 6. Javadoc tags Tag & Parameter Usage Applies to Since @exception classname description @throws classname description Describes an exception that may be thrown from this method. Method @deprecated descriptio n Describes an outdated method. Class, Interface, Enum, Field, Method {@inheritDoc} Copies the description from the overridden method. Overriding Method 1.4.0 {@link reference} Link to other symbol. Class, Interface, Enum, Field, Method {@value #STATIC_FIEL D} Return the value of a static field. Static Field 1.4.0 {@code literal} Formats literal text in the code font. It is equivalent to <code>{@literal}</code> . Class, Interface, Enum, Field, Method 1.5.0
- 7. Examples
- 8. You can include required HTML tags inside the description part, For example, below example makes use of <h1>....</h1> for heading and <p> has been used for creating paragraph break:
- 9. /** * Validates a chess move. * * Use {@link #doMove(int theFromFile, int theFromRank, int theToFile, int theToRank)} to move a piece. * * @param theFromFile file from which a piece is being moved * @param theFromRank rank from which a piece is being moved * @param theToFile file to which a piece is being moved * @param theToRank rank to which a piece is being moved * @return true if the move is valid, otherwise false */ boolean isValidMove(int theFromFile, int theFromRank, int theToFile, int theToRank) { ... } /** * Moves a chess piece. * * @see java.math.RoundingMode */ void doMove(int theFromFile, int theFromRank, int theToFile, int theToRank) { ... }
- 10. import java.io.*; /** * <h1>Add Two Numbers!</h1> * The AddNum program implements an application that * simply adds two given integer numbers and Prints * the output on the screen. * <p> * <b>Note:</b> Giving proper comments in your program makes it more * user friendly and it is assumed as a high quality code. * * @author Zara Ali * @version 1.0 * @since 2014-03-31 */ public class AddNum { /** * This method is used to add two integers. This is * a the simplest form of a class method, just to * show the usage of various javadoc Tags. * @param numA This is the first paramter to addNum method * @param numB This is the second parameter to addNum method * @return int This returns sum of numA and numB. */ public int addNum(int numA, int numB) { return numA + numB; } /** * This is the main method which makes use of addNum method. * @param args Unused. * @return Nothing. * @exception IOException On input error. * @see IOException */ public static void main(String args[]) throws IOException { AddNum obj = new AddNum(); int sum = obj.addNum(10, 20); System.out.println("Sum of 10 and 20 is :" + sum); } }
- 11. Useful Links https://newcircle.com/bookshelf/java_fundamentals_tu torial/javadoc http://agile.csc.ncsu.edu/SEMaterials/tutorials/javadoc / https://msdn.microsoft.com/en- us/library/b2s063f7.aspx