0

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 注释真的只是区分工具自动编写的注释和开发人员编写的注释的一种方式吗？

4

3 回答 3

7

人们使用 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 在浏览代码时脱颖而出。

通常，您维护代码的时间比编写代码的时间要多，因此拥有像这样定义良好的语法是一个好主意 - 它会导致您分配更多时间来思考解决问题，而不是破译大块文本以获取基本信息。

于 2013-03-27T21:32:46.787 回答
3

该表格/** */通常用于文档。所以如果你想记录一个类、一个文件、一个函数、一个类方法、一个类字段或一个变量，你应该使用那种形式。

该表单/* */仅包含代码注释，就像//.

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

于 2013-03-27T21:31:22.437 回答
1

回顾上面的所有评论和讨论，听起来您仍然对仅在函数上使用 Javadoc 评论有疑问。答案是肯定的，您可以对不需要在类定义中的函数使用 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.

这为您提供了函数的返回类型、参数和简短描述。此外，“addSquares”将是指向同一 HTML 页面中更具描述性部分的超链接，类似于：

addSquares
public int addSquares( int x, int y )
对两个数求平方，并返回这些平方数之和。

参数：
x 第一个值平方
y 第二个值平方

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

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

于 2013-08-24T20:47:02.990 回答