Reading:  

Quick walk through the advanced concepts in Java - Part 3 of series


Working with JavaDoc

What is Javadoc?

Javadoc is a tool for generating API documentation in HTML format from doc comments in source code. 

There are three types of comments are supported by java.

Comment

Description

// text

Everything is ignored by compiler from // to end of line.

/* text */

Everything is ignored by compiler from /* to */.

/** documentation */

This are documentation comment and generally known as doc comment. The JDK uses javadoc tool for preparing documentation automatically.

Example

/**
* The program implements an application that
* simply displays "Java!" the standard output.
*
* @author  x
* @version 1.0
* @since   2015-02-07 
*/
public class JavaExample {
    public static void main(String[] args) { 
        System.out.println("Java!");
    }
}

We can include required HTML tags inside description part. Below example use <h1>....</h1> for heading and <p> used for creating paragraph break:

/**
*<h>Java Example</h>
* <p>The program implements an application that
* simply displays "Java!" the standard output.</p>
*
* @author x
* @version 1.0
* @since 2015-02-07
*/
public class JavaExample {
public static void main(String[] args) {
System.out.println("Java!");
}
}

The javadoc Tags:

The javadoc tool recognizes following tags:

Tag

Description

Syntax

@author

Adds author of class.

@author nameofAuthor

{@code}

Displays text in code font without interpreting text as HTML markup or nested javadoc tags.

{@code text}

{@docRoot}

Represents relative path to generated document's root directory

{@docRoot}

@deprecated

Adds comment indicating API should no longer be used.

@deprecated text

@exception

Add Throws subheading to generated documentation

@exception class-name description

{@inheritDoc}

Inherits a comment from nearest inheritable class or implementable interface

Inherits a comment from immediate surperclass.

@param

Adds a parameter with the specified parameter-name followed by the specified description to the "Parameters" section.

@param parameter-name description

@return

Adds a"Returns" section with description text.

@return description

@see

Adds a "See Also" heading with link or text entry those points to reference.

@see reference

@serial

Used in doc comment for a default serializable field.

@serial field-description

@serialData

Documents data written by writeObject( ) or writeExternal( ) methods

@serialData data-description

@serialField

Documents an ObjectStreamField component.

@serialField field-name field-type field-description

@since

Adds a "Since" heading with specified since-text to generated documentation.

@since release

{@value}

When {@value} is used in doc comment of a static field, it displays value of that constant:

{@value package.class#field}

@version

Adds a "Version" subheading with specified version-text to the generated docs when -version option is used.

@version version-text

Eclipse IDE generating JavaDoc

To create JavaDoc with Eclipse IDE, follow these steps

  1. Got Project -> Generate Javadoc

  2. In the "Javadoc command" field - browse to find javadoc.exe On the computers in the Clapp CS lab that is C:\Program Files\Java\jdk1.8.0_20\bin\javadoc.exe On other computers it would be \bin\javadoc.exe

  3. Check the box next to the project/package/file for which you are creating the javadoc

  4. In the "Destination" field browse to find the desired destination (for example, the root directory of the current project).

  5. Don't worry about all other setting on this page

  6. Click "Finish"

More on JavaDoc can be found on official javadoc documetation page on oracle.com which can be found here

http://www.oracle.com/technetwork/java/javase/documentation/javadoc-137458.html

 

We hope you enjoyed this series on Java, Let us know how we can improve ourselves for next round of technologies we cover.

Thanks for reading..

 

Description

This is the last part in our tutorial series on Java. This tutorial is designed as a quick walk through the advanced concepts of Java Languages. This tutorial is subdivided into few chapters as shown below

  1. Data Structures
  2. Collections
  3. Generics
  4. Serialization
  5. Networking 
  6. Working with Emails
  7. Multithreading
  8. Getting started with Applets
  9. JavaDoc

Let us know if you find any issues with this tutorial. Also, if you can provide us with your feedback, that always help us improve.

 



Prerequisites

You must have read Part 1 and Part 2 of our tutorial series on Java.

Audience

Beginners or students looking to brush up their Java knowledge

Learning Objectives

To get an understanding on some of the advanced topics of Java.

Author: Subject Coach
Added on: 10th Mar 2015

You must be logged in as Student to ask a Question.

None just yet!