Comments in Java

 

Comments in code are boon else curse if not used properly. Comments makes code more readable if we write comments whenever necessary.
Comments are not executable so whatever you write in comment part is ignored and won’t get executed.
Comments don’t occur within character or String literals.
You can not nest comment.
There are three types of comments in Java.

1. Single-line comment or an end of line comment

All the text from the ASCII characters // to the end of the line is ignored.
// has no special meaning in comments that begin with /* or /**.

 

2. Multiple-line comment or Multi-line comment or Traditional comment:

All the text from the ASCII characters /* to the ASCII characters */ is ignored.
/* and */ have no special meaning in comments that begin with //.
There should not be space between / and *
Example: Valid multi-line comment

 

3. Javadoc multiple-line comment:

Java doc comments are used to create Java documentation in HTML format from doc comments in source code.
It is similar to multiple line comment but starts with /** and end with */
We use Javadoc tool to generate Java API documentation.

How to know the version of Javadoc ?

Generally Javadoc doesn’t include a version number anywhere in it’s jar file.
By convention Oracle uses same version number for Javadoc as JDK it’s located in. Therefore JDK 8 will have Javadoc version 8.
Javadoc tool comes with JDK. You can check the version of Javadoc tool as shown below in command prompt.
Go to command prompt and type Javadoc –J-version

How to Write Doc Comments?
The special comments in the Java source code that are delimited by the /** … */ delimiters. These comments are processed by the Javadoc tool to generate the API docs.

Javadoc tags
The javadoc command parses special tags when they are embedded within a Java documentation comment. The javadoc tags let you auto generate 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 text. By convention, tags with the same name are grouped together. For example, put all @see tags together.

There are two types of Javadoc tags:
Block tags: Place block tags only in the tag section that follows the description. Block tags have the form: @tag.
Inline tags: Place inline tags anywhere in the main description or in the comments for block tags. Inline tags are enclosed within braces: {@tag}.

Note: Generally we write Javadoc for other people to refer so they can use the API and their methods properly. Hence here we are writing Javadoc for them to use it but not to maintain the code. Therefore only public classes and methods etc. necessary to be documented. For our maintenance of code we can use single-line or multiple-line comments that are very easier.

Therefore Javadoc tags works only for public members, not for protected, package private, private members.

  1. @author:
    Introduced in JDK 1.0
    Used to add name of author in text form. You can provide one @author tag, multiple @author tags, or no @author tags. The @author tag is not critical, because it is not included when generating the API specification, and so it is seen only by those viewing the source code.
  2. {@code text}:
    Equivalent to <code>{@literal}</code>.
    Displays text in code font without interpreting the text as HTML markup or nested Javadoc tags.
  3. @version version-text:
    Introduced in JDK 1.0
    Adds a Version subheading with the specified version-text value to the generated documents when the -version option is used.
  4. @param parameter-name description:
    Introduced in JDK 1.0
    Adds a parameter with the specified parameter-name followed by the specified description to the Parameters section. This tag is valid only in a documentation comment for a method, constructor, or class.
  5. @return description:
    Introduced in JDK 1.0
    Adds a Returns section with the description text. This text should describe the return type and permissible range of values. This tag is valid only in a documentation comment for a method.
  6. @exception class-name description:
    Introduced in JDK 1.0 Identical to the @throws tag.
    adds a Throws subheading to the generated documentation, with the class-name and description text.
  7. {@inheritDoc}:
    Introduced in JDK 1.4.
    Inherits (copies) documentation from the nearest inheritable class or implementable interface into the current documentation comment at this tag’s location. This tag is valid only in the main description block of a method. In this case, the main description is copied from a class or interface up the hierarchy and in the text arguments of the @return, @param, and @throws tags of a method. In this case, the tag text is copied from the corresponding tag up the hierarchy.
  8. @throws class-name description:
    Introduced in JDK 1.2.
    Behaves the same as the @exception tag. The @throws tag adds a Throws subheading to the generated documentation, with the class-name and description text. The class-name is the name of the exception that might be thrown by the method. This tag is valid only in the documentation comment for a method or constructor.
  9. {@link package.class#member label}:
    Introduced in JDK 1.2.
    Inserts an inline link with a visible text label that points to the documentation for the specified package, class, or member name of a referenced class. This tag is valid in all documentation comments:
  10. {@literal text}:
    Introduced in JDK 1.5
    Displays text without interpreting the text as HTML markup or nested Javadoc tags. This enables you to use angle brackets (< and >) instead of the HTML entities (&lt; and &gt;) in documentation comments.
  11. @see reference:
    Introduced in JDK 1.0
    Adds a See Also heading with a link or text entry that points to a reference. A documentation comment can contain any number of @see tags, which are all grouped under the same heading.
  12. @since since-text:
    Introduced in JDK 1.1
    Adds a Since heading with the specified since-text value to the generated documentation.
  13. @serial field-description | include | exclude:
    Introduced in JDK 1.2
    Used in the documentation comment for a default serializable field.
  14. @serialData data-description:
    Introduced in JDK 1.2
    Uses the data description value to document the types and order of data in the serialized form.
  15. @serialField field-name field-type field-description:
    Introduced in JDK 1.2
    Documents an ObjectStreamField component of the serialPersistentFields member of a Serializable class. Use one @serialField tag for each ObjectStreamField component.
  16. @deprecated deprecated-text:
    Introduced in JDK 1.0
    Adds a comment indicating that this API should no longer be used even though it may continue to work.
  17. {@docRoot}:
    Introduced in JDK 1.3
    Represents the relative path to the generated document’s (destination) root directory from any generated page. This tag is useful when you want to include a file, such as a copyright page or company logo, that you want to reference from all generated pages. Linking to the copyright page from the bottom of each page is common.
  18. {@value package.class#field}:
    Introduced in JDK 1.4.
    Displays constant values. When the {@value} tag is used without an argument in the documentation comment of a static field, it displays the value of that constant.

How to add Javadoc in Java program?

First you have to add the Javadoc tags as shown in below example.


How to generate Javadoc using Eclipse IDE?

Please follow shown steps

Click on Project menu then select Generate Javadoc, square boxed in red color in following screenshot.


Select the checkbox of Java application you want to generate Javadoc for, as shown in red arrow.
Here you can see green box where It shows Javadoc tool Javadoc.exe with it’s location in JDK installation folder.
In blue box you can see the location where the generated Javadoc going to be stored.



This is the output you get on the console of Eclipse

This is the location of generated Javadoc you can see that in square red box.
Click on index.html to open generated Javadoc.

How to generate Javadoc using command prompt?
This is where ReverseNumber.java file resides
c:/com/codetechclub/ReverseNumber.java for which we are going to generate Javadoc.
First through command prompt go to the folder where the application file is stored then type
javadoc -d c:/com/codetechclub/doc ReverseNumber.java

Where in -d c:/com/codeteclub/doc   after -d is the location where Javadoc will be generated and stored. After that comes the name of application or file whose Javadoc you want to generate. In our case ReverseNumber.java

Press enter now then you will get following output.

In following screenshot you can see the location in blue box where Javadoc is generated.
In red box you can see index.html click on that to see generated Javadoc.

Let’s have a glimpse of generated Javadoc for ReverseNumber.java


This is how we generate Javadoc. If you have any suggestions please let me know I’ll updated it sooner.

Share and Enjoy !

0Shares
0 0

Leave a Reply

Your email address will not be published. Required fields are marked *