问题标签 [code-documentation]

我知道这不是最重要的问题，但我刚刚意识到我可以将 javadoc 注释块放在注释之前或之后。我们希望采用什么作为编码标准？

我正在浏览我刚刚编写的一些新代码，并将 NDoc 样式注释添加到我的类和方法中。我希望生成一个非常好的 MSDN 样式文档以供参考。

一般来说，在为类和方法编写注释时，有哪些好的指导方针？NDoc 评论应该说什么？他们不应该说什么？

我发现自己在看 .NET 框架评论说什么，但这很快就过时了；如果我可以有一些好的规则来指导自己，我可以更快地完成我的文档。

我们在 c# .net 中开发了一个应用程序，旨在使其可部署在我们的 Intranet 中。我们希望有一个可靠的文档来配合它，但不确定记录它的最佳平台。有什么工具可以促进这个过程？

我发现了有关 Doxygen、Htmlhelp 或 Dr Explain 的信息，但我仍然不知道该使用什么。

public如果某些成员缺少 XML 文档，Visual Studio 有一个很好的功能可以发出一堆编译器警告。

我希望为internal任何非成员提供相同或更好的功能private，但不幸的是，到目前为止，我无法找到如何配置需要 XML 文档的可见性级别。

我承认很久以前就问过同样的问题，但是 OP 没有得到一个答案。

如何在 Xcode 中为我自己的代码创建快速帮助条目？我只是希望它作为编码支持，这意味着在编码 Java 时就像 Eclipse 功能一样。在 Eclipse 中，当将方法悬停在其他地方时，您会在方法上方输入注释。

Xcode 等效项似乎是“快速帮助”。

除了使用 Doxygen 真的没有别的办法了吗？对于我正在从事的小项目来说，Doxygen 似乎有点矫枉过正。目前我确实知道我只想要彻底填充快速帮助，所以请避免任何提示，例如“您必须为您的项目创建文档”。

我真的很感激任何帮助，因为我在这个主题上唯一能找到的就是这个问题。

但如您所见，没有可用的解决方案。

我们是一个开发团队，我们需要记录我们的代码。每个开发人员都在处理可以称为模块的代码的一部分。我们需要具有此规范的文档

1. 它应该易于实现和使用
2. 每个开发人员都记录了她/他自己的工作，当另一个开发人员需要了解任何模块时，他/她不应该有义务向原始开发人员询问文档。他/她应该能够自己找到该文件。
3. 我们应该能够搜索整个文档。

你对此有什么建议吗？

首先，我不是在问如何从 PHP 源代码生成文档。使用 Doxygen 或 PHPDocumentor 之类的库很容易做到这一点。我正在寻找的是一种为类、方法、属性等自动生成基于 phpdoc 的内联注释存根的方法。是否有任何预先存在的库可以做到这一点？我进行了一些搜索，但一无所获。

我只是问，因为我有一种痒，我想自己写。我倾向于一次花费数小时编写代码，将文档保存为最后一步（我知道，我真的应该边做边做）。问题是，即使意识到内联文档的重要性，在连续 8 小时编码和编写具有数十种方法和属性的十几个类之后，不得不停下来开始编写这些东西有点令人反感。

显然，我无法自动创建 COMPLETE 文档。诸如类、属性和方法的详细描述之类的东西必须手动输入。但是，使用反射，我可以轻松获得足够的信息来创建带有填充空白占位符的评论存根。

如果有人可以帮助我寻找这样的解决方案，太棒了。如果没有，我将创建一个新的 Github 存储库并为社区贡献一些有用的东西。:)

我目前正在使用JSDoc Toolkit来记录我的代码，但它不太适合 - 也就是说，它似乎很难正确描述命名空间。假设您的每个文件中有两个简单的类：

lib/database/foo.js：

然后继承了一些东西lib/database/bar.js：

在生成的文档中，这只是作为Fooand输出Bar，没有前导database（或lib.database），当您没有全局范围内的所有内容时，这是非常必要的。

我试过投掷@namespace database，@name database.Foo但结果并不好。

有什么想法可以让 JSDoc 输出更合适的东西，或者一些完全不同的工具可以更好地与 Node.js 配合使用吗？（我简要地查看了 Natural Docs、JSDuck 并轻而易举地浏览了其他一些看起来相当过时的东西......）

我已经编写了一个相当简单的类的文档，但我觉得它不够清楚。我应该改变什么吗？

我正在查看http://www.phpdoc.org/，但想知道你们发现了什么有用。我想要一些有助于记录我们的代码的东西，以及在网站上经常执行的程序和任务。在 linux/PHP/MySQL 环境中，最好的解决方案是什么？