Возможный дубликат:
Имеет ли "/* (не-javadoc)" хорошо понятое значение?
Что означают следующие выражения?
/* (non-Javadoc)
*
* Standard class loader method to load a class and resolve it.
*
* @see java.lang.ClassLoader#loadClass(java.lang.String)
*/
@SuppressWarnings("unchecked")
Я видел это сообщение, сгенерированное Eclipse, когда программист просит Eclipse добавить комментарий Javadoc к некоторому коду в месте, где [EDIT: Eclipse думает] инструмент Javadoc фактически не использует его.
Общим примером является реализация метода в интерфейсе, реализованном классом (который в Java 6 нуждается в аннотации @Override). Javadoc будет использовать javadoc, помещенный в метод в INTERFACE, а не тот, который предусмотрен в реализации.
Остальная часть комментария, скорее всего, была написана человеком, который этого не знал.
Javadoc ищет комментарии, начинающиеся с /**. По традиции комментарии к методам, которые не предназначены для участия в java-документах, начинаются с "/* (не-Javadoc)" (по крайней мере, когда ваша среда для разработчиков является Eclipse).
В стороне, избегайте использования многострочных комментариев внутри методов. Например, избегайте этого:
public void iterateEdges()
{
int i = 0;
/*
* Repeat once for every side of the polygon.
*/
while (i < 4)
{
}
}
Предпочтительно следующее:
public void iterateEdges()
{
int i = 0;
// Repeat once for every side of the polygon.
while (i < 4)
{
++i;
}
}
Причина в том, что вы открываете возможность прокомментировать весь метод:
/*
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)
{
}
}
Теперь вы можете увидеть поведение старого метода при внедрении нового метода. Это также полезно при отладке (для упрощения кода).
/*
* 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 /**
*/
Это просто нормальный комментарий. Примечание означает, что если вы создадите руководство, базу javadoc, этот текст не будет добавлен.