52

Possible Duplicate:
Does “/* (non-javadoc)” have a well-understood meaning?

What does the following statements mean?

    /* (non-Javadoc)
     * 
     * Standard class loader method to load a class and resolve it.
     * 
     * @see java.lang.ClassLoader#loadClass(java.lang.String)
     */
    @SuppressWarnings("unchecked")
Community
  • 1
  • 1
Dr. Mian
  • 3,334
  • 10
  • 45
  • 69

4 Answers4

29

Javadoc looks for comments that start with /**. By tradition, method comments that are not intended to be part of the java docs start with "/* (non-Javadoc)" (at least when your dev environment is Eclipse).

As an aside, avoid using multi-line comments inside methods. For example, avoid this:

public void iterateEdges()
{
  int i = 0;

  /* 
   * Repeat once for every side of the polygon.
   */
  while (i < 4)
  {
  } 
}

The following is preferred:

public void iterateEdges()
{
  int i = 0;

  // Repeat once for every side of the polygon.
  while (i < 4)
  {
    ++i;
  } 
}

The reason is that you open the possibility to comment out the entire method:

/*
public void iterateEdges()
{
  int i = 0;

  // Repeat once for every side of the polygon.
  while (i < 4)
  {
     ++i;
  } 
}
*/

public void iterateEdges()
{
  // For each square edge.
  for (int index = 0; index < 4; ++index)
  {
  }
}

Now you can still see the old method's behaviour while implementing the new method. This is also useful when debugging (to simplify the code).

DwB
  • 37,124
  • 11
  • 56
  • 82
  • 7
    What a redundant convention. :O – Steven Jeuris Dec 06 '12 at 12:20
  • 5
    I'm always tempted to delete these Eclipse-generated comments, since they sometimes comprise a large proportion of many simple classes' textual content without providing any benefit. They don't convey any information that a reasonable IDE or a programmer's common sense can't infer (it's got an @Override annotation, I *know* where I can find the JavaDocs for it...). – Lyle Oct 30 '13 at 02:17
27

I have seen this message generated by Eclipse when the programmer asks Eclipse to add a Javadoc comment to some code in a location where [EDIT: Eclipse thinks] the Javadoc tool will not actually use it.

A common example is the implementation of a method in an interface implemented by the class (which in Java 6 needs the @Override annotation). Javadoc will use the javadoc placed on the method in the INTERFACE, not the one provided in the implementation.

The rest of the comment was most likely written by a person that did not know this.

Thorbjørn Ravn Andersen
  • 73,784
  • 33
  • 194
  • 347
12
/*
 * This is the typical structure of a multi-line Java comment.
 */

/**
 * This is the typical structure of a multi-line JavaDoc comment.
 * Note how this one starts with /** 
 */
Freiheit
  • 8,408
  • 6
  • 59
  • 101
Zoot
  • 2,217
  • 4
  • 29
  • 47
3

It's just a normal comment. The note means, if you create a manual, base of javadoc, this text won't be added.

Reporter
  • 3,897
  • 5
  • 33
  • 47