问题标签 [docstring]

我喜欢用 Doxygen 创建 C 或 PHP 代码的文档。我有一个即将到来的 Python 项目，我想我记得 Python 没有/* .. */注释，并且还有自己的自我文档工具，这似乎是 Python 的文档方式。

由于我熟悉 Doxygen，如何使用它来生成 Python 文档？有什么特别需要我注意的吗？

有没有办法以类似于文档字符串描述模块或功能的方式来描述模块的数据？

在您看来，什么是有意义的文档字符串？你期望在那里被描述什么？

例如，考虑这个 Python 类的__init__：

你觉得这有意义吗？发布您的好/坏示例以供所有人了解（以及一般性答案，以便可以接受）。

是否有一种机制可以注释掉大块 Python 代码？

现在，我能看到的注释掉代码的唯一方法是用 . 开头的每一行#，或者用三引号将代码括起来"""：

这些问题是#在每一行之前插入很麻烦，并且"""使我想用作注释的字符串显示在生成的文档中。

阅读所有评论后，答案似乎是“否”。

测试这样的代码的最佳方法是什么（下面的方法显然失败，而对象每次都在不同的块中创建）：

在 VIM 中编写 Python 时，有什么方法可以查看函数的文档字符串？

例如：

我希望能够以MyFunction(spam0)工具提示或状态栏或 VIM 允许的任何其他方式键入和查看文档字符串。

是否可以以简单的方式将文档字符串添加到命名元组？

我试过

但这并没有削减它。是否有可能以其他方式进行？

编写如下内容是有效的 JavaScript：

字符串实际上什么都不做。有什么理由，为什么不应该以这种方式在 JavaScript 中评论他/她的函数？

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

• 必须启动字符串文字，从长远来看可能代价高昂

• 字符串文字不会被 JS 缩小器识别为可移除

还有其他要点吗？

编辑：为什么我提出这个话题：我在John Resig 的博客上发现了类似的东西，其中新的 ECMA 5 标准使用未分配的字符串文字来启用“严格模式”。现在，我有兴趣评估做此类文档是否有用途或危险。

我正在尝试提高我的 Python 项目中测试的数量和质量。随着测试数量的增加，我遇到的困难之一是知道每个测试的作用以及它应该如何帮助发现问题。我知道跟踪测试的一部分是更好的单元测试名称（已在其他地方解决），但我也有兴趣了解文档和单元测试如何结合在一起。

当这些测试在未来失败时，如何记录单元测试以提高它们的实用性？具体来说，什么是好的单元测试文档字符串？

我很欣赏描述性答案和具有出色文档的单元测试示例。虽然我只使用 Python，但我对其他语言的实践持开放态度。

我在使用带有装饰器的文档字符串时遇到问题。给定以下示例：

现在帮助没有foo按预期向我显示文档字符串，它显示：

没有装饰器，帮助是正确的：

我知道，函数foo是由装饰器包装的，所以函数对象不再是函数foo。但是，按预期获取文档字符串（和帮助）的好解决方案是什么？