JavaScript对象和方法的首选注释方法是什么？

Question

我习惯使用Atlas，那里首选的（据我所知）方法是使用XML注释，例如：

/// <summary>
///   Method to calculate distance between two points
/// </summary>
///
/// <param name="pointA">First point</param>
/// <param name="pointB">Second point</param>
///
function calculatePointDistance(pointA, pointB) { ... }

最近我一直在研究其他第三方JavaScript库，看到类似以下语法：

/*
 * some comment here
 * another comment here
 * ...
 */
 function blahblah() { ... }

还有没有适用于JavaScript的API生成器，可以读取“首选”注释风格作为额外的福利？

- EvilSyn

---

你所说的“Atlas”是什么？是指ATLAS.ti吗？还是指Atlas Documentation？或者是其他什么东西？ - Peter Mortensen

好的，OP已经离开了（“最后一次出现超过6年”）。还有其他人可以加入吗？ - Peter Mortensen

如果您正在使用Visual Studio Code，您可以键入/**然后按Tab键进行自动完成。 - SendETHToThisAddress

Answer 1

这里有JSDoc

/**
 * Shape is an abstract base class. It is defined simply
 * to have something to inherit from for geometric 
 * subclasses
 * @constructor
 */
function Shape(color){
 this.color = color;
}

- Chris MacDonald

---

你也可以使用 https://github.com/hosseinmd/prettier-plugin-jsdoc 来格式化注释。 - Hossein Mohammadi

Answer 2

越简单越好，注释很好用，记得使用它们 :)

var something = 10; // My comment

/*
Lorem ipsum dolor sit amet, consectetur adipisicing elit,
sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.
Ut enim ad minim veniam, quis nostrud exercitation ullamco
nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor
in reprehenderit in voluptate velit esse cillum dolore eu
fugiat nulla pariatur.
*/

function bigThing() {
    // ...
}

但对于自动生成的文档...

/**
 * Adds two numbers.
 * @param {number} num1 The first number to add.
 * @param {number} num2 The second number to add.
 * @return {number} The result of adding num1 and num2.
 */
function bigThing() {
    // ...
}

- molokoloco

---

我不同意“越简单越好”的说法，你应该在你的IDE中安装一个注释插件来自动生成第二种风格，因为它更有帮助。 - vsync

简单就是更好。代码应该是自解释的和声明式的。注释应该只用来解释选择、决策、经验教训和采取的方向等。 - undefined

Answer 3

雅虎提供了YUIDoc。

它有很好的文档支持，由雅虎支持，并且是一个Node.js应用程序。

它还使用了很多相同的语法，因此从一个到另一个并不需要做太多更改。

- Chris MacDonald

Answer 4

第一个例子中三重注释的使用实际上是为了外部XML文档工具和(在Visual Studio中)智能感知支持。它仍然是一个有效的注释，但是它是特殊的 :) 实际的注释“运算符”是//。唯一的限制是它只能用于单行。

第二个例子使用C样式的块注释，允许跨多行或在行中间进行注释。

- Jim Burger

---

没错 - 我最近读到它正在被逐步淘汰（至少对于JS支持），这就是我问这个问题的原因。谢谢！ - EvilSyn

Answer 5

尝试将以下内容粘贴到Visual Studio 08中的JavaScript文件中，并进行操作：

var Namespace = {};
    Namespace.AnotherNamespace = {};

Namespace.AnotherNamespace.annoyingAlert = function(_message)
{
    /// <param name="_message">The message you want alerted two times</param>
    /// <summary>This is really annoying!!</summary>

    alert(_message);
    alert(_message);
};

智能感知大放异彩！

有关此内容的更多信息（包括如何引用外部JavaScript文件以供大型库使用），请参见Scott Gu的博客。

- roosteronacid