Answers:
第一种形式称为Javadoc。在为javadoc
工具编写由该工具生成的形式化API时,可以使用它。例如,Java 7 API页面使用Javadoc并由该工具生成。
您将在Javadoc中看到一些常见的元素,包括:
@param
:用于指示将哪些参数传递给方法,以及它们应具有的值
@return
:用于指示该方法将返回的结果
@throws
:用于指示在某些输入的情况下方法抛出异常或错误
@since
:用于指示此类或函数可用于的最早的Java版本
例如,以下是Javadoc的compare
方法Integer
:
/**
* Compares two {@code int} values numerically.
* The value returned is identical to what would be returned by:
* <pre>
* Integer.valueOf(x).compareTo(Integer.valueOf(y))
* </pre>
*
* @param x the first {@code int} to compare
* @param y the second {@code int} to compare
* @return the value {@code 0} if {@code x == y};
* a value less than {@code 0} if {@code x < y}; and
* a value greater than {@code 0} if {@code x > y}
* @since 1.7
*/
public static int compare(int x, int y) {
return (x < y) ? -1 : ((x == y) ? 0 : 1);
}
第二种形式是块(多行)注释。如果要在注释中包含多行,请使用此选项。
我会说,你只需要使用后者的形式谨慎 ; 也就是说,您不想用不描述方法/复杂函数应该具有的行为的块注释来使代码负担重。
由于Javadoc在这两者中更具描述性,并且您可以通过使用它生成实际的文档,因此使用Javadoc比简单的块注释更可取。
对于Java 编程语言,两者之间没有区别。Java有两种类型的注释:传统注释(/* ... */
)和行尾注释(// ...
)。请参阅Java语言规范。因此,对于Java编程语言,两者/* ... */
和/** ... */
都是传统注释的实例,并且它们都被Java编译器完全相同地对待,即,它们被忽略(或更正确地说:它们被视为空白)。
但是,作为Java程序员,您不仅会使用Java编译器。您使用了整个工具链,其中包括例如编译器,IDE,构建系统等。其中一些工具与Java编译器的解释方式有所不同。特别是,/** ... */
注释由Javadoc工具解释,该工具包含在Java 平台中并生成文档。Javadoc工具将扫描Java源文件并将它们之间的部分解释/** ... */
为文档。
这类似于标签如FIXME
and TODO
:如果您包含诸如// TODO: fix this
或的注释// FIXME: do that
,则大多数IDE都会突出显示此类注释,以使您不会忘记它们。但是对于Java,它们只是注释。
javadoc
工具无法解释某些内容。
阅读JLS的3.7节很好地解释了有关Java注释的所有知识。
有两种注释:
- / *文字* /
传统注释:从ASCII字符/ *到ASCII字符* /的所有文本都将被忽略(与C和C ++一样)。
- //文本
行尾注释:从ASCII字符//到行尾的所有文本都将被忽略(与C ++中一样)。
关于你的问题
第一个
/**
*
*/
用于声明Javadoc技术。
Javadoc是一种工具,用于解析一组源文件中的声明和文档注释,并生成一组描述类,接口,构造函数,方法和字段的HTML页面。您可以使用Javadoc doclet定制Javadoc输出。doclet是用Doclet API编写的程序,用于指定该工具要生成的输出的内容和格式。您可以编写doclet来生成任何类型的文本文件输出,例如HTML,SGML,XML,RTF和MIF。Oracle提供了用于生成HTML格式API文档的标准doclet。Doclet还可以用于执行与生成API文档无关的特殊任务。
有关更多信息,Doclet
请参阅API。
正如JLS中清楚解释的那样,第二个将忽略之间的所有文本/*
,*/
因此可用于创建多行注释。
您可能想了解有关Java注释的其他一些信息
/* and */
以开头的注释没有特殊含义//
。//
以开头的注释没有特殊含义/* or /**
。因此,以下文本是一个完整的注释:
/* this comment /* // /** ends here: */
我认为现有的答案不足以解决问题的这一部分:
我什么时候应该使用它们?
如果要编写将在组织内发布或重用的API,则应为每个public
类,方法和字段以及protected
非final
类的方法和字段编写全面的Javadoc注释。Javadoc应该涵盖方法签名无法传达的所有内容,例如前置条件,后置条件,有效参数,运行时异常,内部调用等。
如果您正在编写内部API(同一程序的不同部分使用的内部API),那么Javadoc的重要性可能会降低。但是,为了维护程序员的利益,您仍然应该为任何方法或字段(其用法或含义不立即显而易见)编写Javadoc。
Javadoc的“杀手级功能”是它与Eclipse和其他IDE紧密集成。开发人员只需将鼠标指针悬停在标识符上即可了解他们需要了解的所有内容。对于经验丰富的Java开发人员而言,不断引用文档已成为其第二天性,从而提高了他们自己代码的质量。如果您的API未随Javadoc一起记录,那么经验丰富的开发人员将不希望使用它。
以下Java代码清单中的注释为灰色字符:
/**
* The HelloWorldApp class implements an application that
* simply displays "Hello World!" to the standard output.
*/
class HelloWorldApp {
public static void main(String[] args) {
System.out.println("Hello World!"); //Display the string.
}
}
Java语言支持三种注释:
/* text */
编译器会忽略从/*
到的所有内容*/
。
/** documentation */
这表示文档注释(简称doc注释)。编译器会忽略此类注释,就像它会忽略使用/*
和的注释一样*/
。JDK javadoc工具在准备自动生成的文档时使用doc注释。
// text
编译器将忽略从//
行尾到行尾的所有内容。
现在,考虑何时使用它们:
使用// text
时,您要评论的一行代码。
使用/* text */
时,您要评论的多行代码。
使用/** documentation */
时,你会想加入,可用于自动生成程序文档的程序的一些信息。