Question

选择javadoc / phpdoc比定期评论有什么理由和情况？我知道语法差异是什么，但为什么要使用其中一个。它主要是语义还是其他原因，我应该使用一个而不是另一个，它们是什么？

我真的不明白javadoc / phpdoc评论的目的。下一个代码块有什么问题？ ...... /**只是让某些评论在编辑器中变成不同颜色的一种方式...有些编辑不区分（香草崇高似乎不是）？

/*
 * This block is wrapped in /** */ not /* */
 * Some documentation goes here
 * Below is copied from http://www.oracle.com/technetwork/java/javase/documentation/index-137868.html
 * @param  url  an absolute URL giving the base location of the image
 * @param  name the location of the image, relative to the url argument
 * @return      the image at the specified URL
 * @see         Image
 */

另一个问题......我有理由在同一档案中同时使用/** */和/* */吗？

最后的问题......为什么javadoc / phpdoc评论似乎与类有关...但是我看到它们被用作对我最初理解的页面的介绍性评论？

实际上是另一个......冒着回答我自己的问题的风险我想知道javadoc / phpdoc注释真的只是区分工具自动编写的注释和开发人员编写的注释吗？ / p>

Answer 1

人们使用Javadoc的全部原因是一致性和可读性 - 如果您知道语法，则可以轻松查看其他人的代码（反之亦然），并立即明白其含义。而不是像：

// This method is used for counting sheep just before bed time
// It's really awesome, and takes the bed-time, and also age,
// And also number of sheep, in reverse order.

需要时间来处理;它更好看：

/**
 * Count the number of sheep at bedtime
 *
 * @author Tom Walters 
 *
 * @param sheep   The number of sheep to count
 * @param age     The age of the person going to bed
 * @param bedTime The time of going to bed in 24hr format
 * @return The sheep were counted successfully
 */

您可以立即看到有多少参数，以及每个参数的用途。返回类型也是如此。当团队合作让作者在那里工作时，它也非常有用，然后你知道当羊走入歧途时谁会大喊大叫。

至于/** - 它有助于将这种风格与随机评论和在线评论等区分开，并且是一种很好的约定，可以帮助Javadoc在浏览代码时突出。

作为一项规则，你将比编写代码更多地维护代码，因此拥有这样一个明确定义的语法是一个好主意 - 这将导致你分配更多的时间来考虑解决问题，而不是解密大块文本以获取基本信息。

Answer 2

表单/** */通常用于文档。因此，如果您想要记录类，文件，函数，类方法，类字段或变量，您应该使用该表单。

表单/* */只包含代码注释，就像//一样。

某些IDE将使用/** */块中包含的phpDoc信息来向您显示一些提示。此外，像phpDocumentor这样的软件使用/** */块来生成文档文件。

Answer 3

通过上面的所有评论和讨论，听起来你仍然有关于单独使用Javadoc评论的问题。答案是 YES ，您可以对不需要在类定义中的函数使用javadoc注释。

为什么在常规评论中使用javadoc评论？主要原因是使用Javadoc工具，该工具将创建一个本地API（html）参考文档，该文档解释了如何使用函数以及期望从这些函数（和类方法）获得的返回类型。如果没有javadoc注释，Javadoc工具将无法放入生成的API文档中。您在javadoc注释中添加的内容将被格式化为您自己的API的html文件。 javadoc工具将/ **视为特殊注释并读取该内容。 Java编译器（或PHP解释器）将看到/ **并认为它是/ *忽略所有内容直到下一个* /，它们将其视为任何常规注释。

因此，如果您打算使用易于阅读的可点击链接参考文档，那么javadoc注释是绝对必要的，如果没有，它们没有任何区别。但是，将Javadoc API作为参考可以节省大量时间，无需在代码中查找函数即可查看函数。

拥有我的文件的Javadoc API，如果我需要其他人帮助项目，那就太棒了。单击Web浏览器中的超链接以查看函数的说明，而不是查找文件，打开文件，查找函数，读取代码并确定其功能，这样会更容易。

让我们使用这个例子：

public int addSquares( int x, int y ) {
  int value = x*x + y*y;
  return value;
}

在它本身你必须阅读这个函数需要两个整数，两个正方形并返回两个正方形的总和。如果我们使用Javadoc函数：

/**
* Squares two numbers, and returns the sum of those squared numbers.
* @param x first value to square
* @param y second value to square
* @return value of x*x + y*y
*/

如果您通过Javadoc工具运行.java文件，那么您将拥有一个显示以下内容的html文件：

int addSquares( int x, int y )
    Squares two numbers, and returns the sum of those squared numbers.

这将为您提供函数的返回类型，参数和简短描述。另外＆＃39; addSquares＆＃39;将是指向同一HTML页面中描述性更强的部分的超链接，其类似于：

<强> addSquares
public int addSquares（int x，int y）
将两个数字平方，并返回这些平方数的总和
参数：的
x第一个值到方形
y第二个值到方形

返回：的
x * x + y * y的值

是的，对于这个例子，阅读代码非常简单，但是当你的函数/方法/类变得更复杂时，使用由Javadoc注释创建的文档引用API要快得多。因此，除非您计划创建参考API文档，否则javadoc注释与常规注释没有什么不同，除了它们在编辑器中提供不同的颜色。

选择javadoc / phpdoc比定期评论有什么理由和情况？

3 个答案: