问题标签 [documentation]

我即将开始一个项目，我将是唯一一个编写实际代码的人，两名经验不足的程序员（害怕认为自己是有经验的！）将在一般情况下观看并提出建议。

是否有一个好的（免费）系统可以用来根据我编写的代码为类和函数提供文档？这可能会对他们掌握数据结构有很大帮助。

因此，对于常用的东西，我有一些扩展方法，并且在记录它们时，我突然想到我不知道如何summary在 XML 注释中一致地编写标记。例如：

对比

所以，问题似乎是我不知道如何始终如一地引用那个讨厌的this参数。此外，我不知道如何清楚地表明这是一种扩展方法（因为我不确定 Sandcastle 和其他工具是否已经赶上它们并且可以自动注释文档以显示它）；我不想以后不得不撕掉所有的手动文档。

所以问题是，对于记录扩展方法有什么指导？如果没有正式的指导，你们都是怎么处理的？如果我们还没有，我们可以对某事进行投票，以便我有事可做吗？作为一个强迫性控制狂，这种不一致让我发疯。

我过去见过的 Latex-to-html 转换器非常糟糕。编辑原始 html 并不好玩，而且似乎不能很好地转换为打印页面。其他人如何解决这个问题？示例链接（pdf 和 html）会很棒。

补充：刚刚问了另一个类似的问题：

我应该为项目文档使用什么格式语言

开始使用 Apache ServiceMix 的权威指南是什么？网站上的操作方法和指南过于复杂，无法从头开始。

在 RDoc 中，有没有办法显示不断的评论？我想在我的一个项目中评论一个常量，但意识到它们没有出现在 RDoc 输出中。我检查了可能对其常量有评论的文档，但从未看到任何（http://www.ruby-doc.org/core/classes/Math.html）。

他们可能会在常量旁边显示实现，因为假设这是不言自明的，但似乎评论也会有所帮助。

谁能告诉我在哪里可以找到完整的 ASP.NET MVC beta 文档？

我正在编写一个应用程序，除其他功能外，它还生成 MSSQL 数据库（对象、表、表数据）的 MediaWiki 文档。

我的问题是您喜欢或需要制作哪种文档格式。我有太多想法要遵循，所以你的回答应该确定我的优先级；）

（我知道在 SO 上还有其他与文档相关的问题，但它们主要涉及如何生成文档（我知道如何），并且不要求特定的文档类型或平台）

编辑：感谢您的评论。实际上我已经有了表关系，因为我解析了外键。但是完整的交叉引用可能有点棘手；）

但是，该问题旨在询问文档类型，例如 Word、PDF、ODF 等。您的专业要求或偏好是什么？

更新： 生成的文档概述

我正在接管一个商业网站的开发。该站点由另一位程序员开发了两年多。这主要是一项单人工作（维护和扩展站点）。当其他程序员向我展示系统时，我将有 2-3 天的过渡期。但据我所知，文档很少。一切都在代码中（有文档记录）。到目前为止，这是我打算问的问题：

• 解释系统中最复杂的元素
• 整体架构描述
• 支持工具的描述（IDE设置、单元测试、部署机制）
• 他用来影响系统架构的任何书籍、网站、播客

还有其他我想念的吗？

[编辑] 谢谢大家。失去好的建议。我希望我能接受多个答案！此外，我还要补充：

• 你具体做了什么来提高系统的性能，现在的瓶颈在哪里？
• 与此相关，您在系统安全方面做了哪些工作？（你做了什么，现在的安全漏洞在哪里）

最后一件事：开发人员说，如果我需要，他稍后会回答我的问题。毕竟是他的“宝贝”。但我真的认为，在 6 个月内他会继续前进，他的可用性会大大减少！

在使用诸如 System.Data.Odbc 或 System.Data.OracleClient 之类的命名空间时，各种数据读取器方法通常需要为函数提供与列对应的整数（例如OracleDataReader.GetInt32）。

我的问题是，使用这些函数的最佳方法是什么，以使代码具有相当的自我记录性。现在，在我看来，有三个选择，即：

这些技术中的每一种似乎都有自己的优点和缺点，我很想知道其他人的想法，或者是否有更好的方法来做到这一点。

我正在尝试为我们的供应商之一为我们正在集成的应用程序提供的 Web 服务编写一些文档。一堆接口是在 Web 服务本身中定义的自定义对象。供应商强烈反对为此应用程序提供任何文档，因此我自己承担了为他们完成工作的责任[根据我更好的判断]。

他们坦率地提供的文档令人尴尬，我正在尝试尽可能短地完成这些工作，以便将一些高质量的文档放在一起。我知道，由于我无法访问他们的源代码，我不能只通过 nDoc/Sandcastle 运行它来吐出 API 文档，但我想知道（作为中途之家）是否有一种简单的方法来将智能感知导出到文本文件，而无需编写实用程序来专门迭代定义的每个对象类型并将成员反映到文本中？

如果我能做到这一点，它至少可以确保我有一个高质量的文档结构，我可以在其中填写空白。必须来回跳到 Visual Studio 来检查每个班级成员的智能感知是一种非常费力的方法。

有没有人有任何想法？