像Python Docstrings一样对JavaScript函数进行注释

Question

编写以下代码是有效的 JavaScript：

function example(x) {
    "Here is a short doc what I do.";
    // code of the function
}

这个字符串实际上并没有起到作用。有没有什么理由，一个人不应该用这种方式在JavaScript中注释他/她的函数？

我在写这个问题时想到了两点：

• 字符串字面量必须被初始化，这可能会在长期运行中消耗大量资源。

• JS缩小器将无法识别字符串字面量可移除性。

还有其他方面需要考虑吗？

编辑：为什么我提出这个话题：我在John Resig的博客上发现了类似于这样的内容，新的ECMA 5标准使用未分配的字符串文字来启用"严格模式"。现在我的兴趣只是评估，在进行这样的文档编写时是否存在用途或危险。

- Boldewyn

---

那么这样做的好处是什么呢？ - mjv

你不是在写Python，所以不要假装自己是。 - Matt Ball

实际上，YUI压缩器识别它是可移除的并将其删除。 - Eli Grey

@mjv：...来尝试和评估一种语言的特性。你从未玩过乐高（TM）吗？ - Boldewyn

我同意，我只是想看看是否有做这件事的必要。 - Boldewyn

如果您希望在运行时可用此字符串，您可以使函数在响应某些特殊参数时返回它。 - alxx

Answer 1

在Javascript中这样做其实没有什么意义。在Python中，将字符串作为函数、类或模块的__doc__成员提供。所以这些文档字符串可用于内省等操作。

如果你在Javascript中创建这样的字符串，与使用注释相比，你没有任何好处，反而会有一些缺点，比如该字符串总是存在。

- Ned Batchelder

---

有些JavaScript引擎会进行优化并删除该字符串。在Spidermonkey中，(function(){"foobar"}).toString(-1) === "function () {}"。 - Eli Grey

很酷，但是在JavaScript中这样做仍然没有任何收益。为什么要破坏语言的设计呢？ - Ned Batchelder

我不确定它是否是Subversion：http://ejohn.org/blog/ecmascript-5-strict-mode-json-and-more/ - Boldewyn

你可以修改这个技巧，以便获得内省和能够在交互式JavaScript shell中查看字符串的好处：`foo = function(bar) { return bar * bar }; foo.__doc__ = 'foo(bar): returns bar squared';`然后在shell中，你会得到类似于这样的东西：> foo { [Function] __doc__: 'foo(bar): returns bar squared' } - Vineet

Answer 2

我正在寻找一种在不用添加\n的情况下添加多行字符串到代码中的方法。看起来这个模块符合要求：https://github.com/monolithed/doc 不幸的是，注释在缩小后将无法保留，但我想你可以编写一个编译任务将文档字符串转换为"\n"格式。

- adampasz

---

这很有趣，但请耐心等待，我没有看到与问题相关的内容。顺便说一下，欢迎来到StackOverflow！ - Boldewyn

这是JS中等同于Python docstring的东西。因此，您可以将文档添加为注释，然后通过__doc__属性访问它。您可以在此处的测试中看到一些示例： https://github.com/monolithed/__doc__/blob/master/tests/__doc__.js我不完全清楚您想要做什么，但您可以使用此方法进行文档编写。 - adampasz

啊，我明白了：我在标准的JS注释中拥有Python的__doc__的优势，所以不需要用字符串进行实验...好主意。（我提出问题的初衷是为了评估在不分配字符串的情况下使用它们的可能性，但我同意，如果没有用例，这是毫无意义的。） - Boldewyn

顺便说一下，我不是很喜欢__doc__.js修改对象原型的方式。但是你可以像我在这里的extractFirstComment函数中那样，通过正则表达式轻松地从函数中提取注释：https://github.com/adampasz/docopt-js-shim/blob/master/index.js - adampasz

对于今天阅读这篇文章的任何人来说，模板文字在ES2015中引入，可以方便地使用多行字符串，而无需显式使用\n字符。 - Magnus Lind Oxlund