问题标签 [documentation]

基本要求是：

• 人类可读/文本格式（便于版本控制）
• 在线（用于协作）
• 轻松格式化（markdown ok，html 太多了）
• 严格的格式（所以作者不会发明新类型的标题、项目符号等）
• 可导出为 PDF、HTML
• 轻松备份和部署（因此我们可以作为只读版本“部署”到客户站点）

我们正在考虑使用某种 wiki 引擎，但它需要使用文件进行存储或对客户有其他“部署”方式，并且易于安装/维护。此外，它必须是免费/便宜的（confluence 太贵了）

有什么建议么？

编辑：我不是在寻找记录代码的工具，我们已经使用 Sandcastle 进行了介绍。

什么是发行说明以及谁阅读它们？他们应该/可以通过为当前版本吐出错误修复来实现自动化，还是需要仔细的人工编辑？那么，任何人都可以链接到关于软件发行说明的最佳实践（背后的推理）？

记录软件设计和架构的最佳实践和软件工具是什么？

1. 基于 Java 或 .NET 的基于 PC 的应用程序？

2. 基于 VxWorks 或嵌入式 Linux 或 Windows CE 的嵌入式应用程序？

我想到的一个工具是Enterprise Architect。这是一个不错的选择吗？

我正在尝试评论我向客户公开的 API (.Net)。我通过使用 XML 注释和通过 SandCastle 提取来做到这一点。

这一切都很好而且很花哨，但是我对 API 进行了单元测试，并且认为这些代码可以很好地放在示例标签中。

那么有人知道提取单元测试代码并放入示例标签的好方法吗？或者有人有更好的想法吗？

当然，我使用 API 重新分发单元测试，但最好将它们包含在文档中。

我只读过关于 Merb 的好东西，但网站上的文档基本上是 api 参考，目前还没有出版书籍。

有关于 Merb 的资源吗？

我想我会开始阅读代码，但如果有其他信息来源会很好

为了在 XML 注释/文档中引用类的成员，您必须使用以下标记：

最好在这里解释一下。

您如何引用索引器？

我的意思是，像这样的成员：

提前致谢。

我正在寻找关于 Javascript 引擎内部的书籍/文章/论文，这些书籍/文章/论文是关于 JVM 内部、CLR 内部等的许多参考作品。我可以（并且可能会）查看 JavaScriptCore 和 V8/Chromium 的源代码，但如果那里有一本书或其他一些“导游”文档，我宁愿先阅读它们。谢谢。

常识告诉 Doxygen 注释块必须放在类、结构、枚举、函数、声明所在的头文件中。我同意这是一个合理的论点，因为库的意思是在没有源代码的情况下分发（只有标头和带有目标代码的库）。

但是......当我开发公司内部（或作为我自己的副项目）库时，我一直在考虑完全相反的方法，该库将与其完整源代码一起使用。我建议将大的注释块放在实现文件（HPP、INL、CPP 等）中，以免弄乱标头中声明的类和函数的接口。

优点：

• 头文件中的混乱更少，只能添加功能的分类。
• 例如，使用 Intellisense 时预览的注释块不会发生冲突 - 这是我在 .H 文件中有函数的注释块并且在同一个 .H 文件中有其内联定义时观察到的缺陷但包含在 .INL 文件中。

缺点：

• （显而易见的）注释块不在声明所在的头文件中。

那么，您有什么想法和可能的建议？

早上好，下午，晚上或晚上（取决于您的时区）。

这只是关于 C# 中 XML 注释的一般问题。我从来没有非常热衷于评论我的程序，我一直是一个冗长的变量/属性/方法命名器，让代码自己说话。如果我正在编写相当混乱的代码，我会写评论，但在大多数情况下，我不会写很多评论。

我正在阅读 .NET、Sandcastle 中的 XML 注释和 codeplex 上的帮助文件生成器，它让我走上了想要记录我的代码并为那些必须深入研究我的人生成一些很好、有用的文档的道路。当我不再在这里时的代码。

我的问题是关于标准和约定的。是否有“好的”XML 注释指南？你应该评论每一个变量和属性吗？每种方法？我基本上只是在寻找有关如何编写好的注释的提示，这些注释将由 sandcastle 编译成好的文档，这样其他程序员在最终不得不处理我的代码时就不会诅咒我的名字。

提前感谢您的意见和建议，Scott Vercuski

我正在尝试在我的 WAMPServer 设置上运行 PHPDocumentor。它运行良好，但我想排除某些目录，例如不包含我自己的代码的 \sqlbuddy\。具有讽刺意味的是，PHPDocumentor 似乎忽略了我的 --ignore 开关。我尝试了几种表达相同事物的方法，但结果相同。下面是我运行它的命令：

非常感谢。