Java Community | Help. Code. Learn.•7mo ago

Week 72 — What is a Javadoc comment and how is it different from other comments?

Question of the Week #72

What is a Javadoc comment and how is it different from other comments?

2 Replies

Comments generally don't impact the execution of (Java) code. It is possible to start a single-line comment with // while a multi-line comment can be started with /* and ended with */. When a multi-line comment before a class, method and field starts with /** instead of */, it is called a "Javadoc comment". These can be picked up by the javadoc tool which can automatically generate documentation. For example, it is possible to write a class like this:

/**
  Creates greetings.
  This class contains methods to greet people
*/
public class Greetings{
  /**
    Greet a person by saying "Hi".
    Concatenates "Hi " with the name of a person
    @param name The name of the person to greet
    @return "Hi" followed by the value of someParam
  */
  public String addToHi(String name){
    return "Hi " + someParam;
  }
}

/**
  Creates greetings.
  This class contains methods to greet people
*/
public class Greetings{
  /**
    Greet a person by saying "Hi".
    Concatenates "Hi " with the name of a person
    @param name The name of the person to greet
    @return "Hi" followed by the value of someParam
  */
  public String addToHi(String name){
    return "Hi " + someParam;
  }
}

With that class in a file Greetings.java, it is possible to run javadoc Greetings.java -d docs and the javadoc tool will generate HTML documentation in a directory named docs.

📖 Sample answer from dan1st

Eric McIntyre•7mo ago

Javadoc comments are a special /** and are meant to describe the specification of the code from an implementation-free perspective, to be read by developers who might use your code. Javadoc comment serves a different purpose from inline comments and multi-line Java comments. Whereas inline and block Java comments are read by other developers who maintain the code, Javadoc comments are for developers who use your code.

Submission from wildbaby2963

Gaming

Programming

Week 72 — What is a Javadoc comment and how is it different from other comments?