/* (non-javadoc) meaning

Question

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")

Solution 1

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).

Solution 2

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.

Solution 3

/*
 * 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 /** 
 */

Solution 4

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

View more solutions

Comments

[Zoot]

@Freiheit Thanks for the edit. The distinction is better now.

[matbrgz]

@Tom, no need to put the programmer down. in Java programming it is close to impossible to be an expert on all relevant technologies.

[Paŭlo Ebermann]

Actually, if you provide the comment with /**, it would be used instead of the interfaces method. (And having it in the source even if not used has the benefit to be there when one reads the source.)

[Steven Jeuris]

What a redundant convention. :O

[Lyle]

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...).

[mercurytw]

Thanks @PaŭloEbermann for a great tip!

[Andrea Bori]

@simpleuser because ( I assume that ) the "real" doc comment it's placed elsewhere.