DocumentationComments.java

package Phase1_CoreLanguage.Comments;

/**This type of comments are used generally when writing code for a project/software package, since it helps to generate a
 * documentation page for reference, which can be used for getting information about methods present, its parameters, etc.
 * For example http://docs.oracle.com/javase/7/docs/api/java/util/Scanner.html is an auto generated documentation page
 * which is generated by using documentation comments and a javadoc tool for processing the comments.
 * <p>
 *
 * Syntax:
 * <p>
 *
 * /**Comment start
 * *
 * *tags are used in order to specify a parameter
 * *or method or heading
 * *HTML tags can also be used
 * *such as <h1>
 * *
 * *comment ends
 * **/

//Java program to illustrate frequently used
// Comment tags

/**
 * <h1>Find average of three numbers!</h1>
 * The FindAvg program implements an application that
 * simply calculates average of three integers and Prints
 * the output on the screen.
 * <p>
 *
 * @author  Deepak Gupta
 * @version 1.0
 * @since 2026-02-18
 */

public class DocumentationComments {
    /**
     * This method is used to find average of three integers.
     * @param numA This is the first parameter to findAvg method
     * @param numB  This is the second parameter to findAvg method
     * @param numC  This is the second parameter to findAvg method
     * @return int This returns average of numA, numB and numC.
     */
    public int findAvg(int numA, int numB, int numC)
    {
        return (numA + numB + numC)/3;
    }

    /**
     * This is the main method which makes use of findAvg method.
     * @param args Unused.
     * @return Nothing.
     */

    public static void main(String args[])
    {
        DocumentationComments obj = new DocumentationComments();
        int avg = obj.findAvg(10, 20, 30);

        System.out.println("Average of 10, 20 and 30 is :" + avg);
    }

    //OUTPUT
    //Average of 10, 20 and 30 is :20
}



/**
 * TAG	DESCRIPTION	SYNTAX
 * @author Adds the author of a class.	@author name-text
 * {@code}	Displays text in code font without interpreting the text as HTML markup or nested javadoc tags.	{@code text}
 * {@docRoot}	Represents the relative path to the generated document’s root directory from any generated page.	{@docRoot}
 * @deprecated Adds a comment indicating that this API should no longer be used.	@deprecated deprecatedtext
 * @exception Adds a Throws subheading to the generated documentation, with the classname and description text.	@exception class-name description
 * {@inheritDoc}	Inherits a comment from the nearest inheritable class or implementable interface.	Inherits a comment from the immediate surperclass.
 * {@link}	Inserts an in-line link with the visible text label that points to the documentation for the specified package, class, or member name of a referenced class.	{@link package.class#member label}
 * {@linkplain}	Identical to {@link}, except the link’s label is displayed in plain text than code font.	{@linkplain package.class#member label}
 * @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 the description text.	@return description
 * @see    Adds a “See Also” heading with a link or text entry that points to reference.	@see reference
 * @serial Used in the doc comment for a default serializable field.	@serial field-description | include | exclude
 * @serialData Documents the data written by the 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 the specified since-text to the generated documentation.	@since release
 * @throws The @throws and @exception tags are synonyms.	@throws class-name description
 * {@value}	When {@value} is used in the doc comment of a static field, it displays the value of that constant.	{@value package.class#field}
 * @version Adds a “Version” subheading with the specified version-text to the generated docs when the -version option is used.	@version version-text**/