问题标签 [documentation-generation]

我目前工作的软件组最近决定开始记录我们的代码库。他们最初采用的方法是使用内置的三斜杠 /// 记录方法。

我们开始发现的一个新问题是，通过 doxygen 运行它的结果是代码库的一个非常好的表示，但供程序员使用，我们原本打算让我们的系统工程师阅读这个文档，他们经常会来我们问一个任务到底在做什么。

有没有一种简单的方法来使用 /// 方法和 doxygen 来记录我们的代码，如果我们以某种方式运行它，我们可以生成一个文档，该文档只包含系统工程版本的文档，而不需要所有额外的绒毛标准程序员文档会吓跑系统人员，例如方法和成员变量等？也欢迎任何替代解决方案建议。

很抱歉，如果这对我们要完成的工作有点混乱，我可以在收到回复时进行调整。谢谢。

我是doxygen的忠实粉丝，多年来我一直使用各种语言。特别是，我很欣赏它类似于 wiki 的能力，可以包含图像并运行 Graphviz 点生成器，以从内联 DOT 代码或外部文件中获得任意内联图。

RDoc具有使用 Graphviz 生成类图的图表支持，但我看不到任何包含任意图像或图表的方法。它似乎也不支持建立像氧气这样的任意页面。

是否有任何工具可以为 Ruby 提供这些 Doxygen 风格的功能？

我浏览了 Ruby Toolbox工具列表，它们似乎都是 RDoc 的变体。

目前对我来说最可能的解决方案似乎是扩展 Yard。

我们有一个可以追溯到 ASP 时代的非常古老的应用程序，我们正在逐步将其重构为 ASP.NET + VB.NET 代码库。

它包含许多具有以下类型的文件：

aspx、asmx、ascx、vb、js (JavaScript)、html、vbs (VBScript)。

后端数据库是带有大量存储过程的 SQL Server 2005。

我们想创建一个从代码文件中的注释自动生成的代码文档。我非常喜欢 Doxygen，但似乎它不支持上述技术。您能否推荐一些文档生成器工具，最好是单个工具或一组工具？

非常感谢。

阿吉特。

公共 c++ 头文件必须提供大量注释。doxygen 注释很难格式化和包装。是否存在一些格式化工具？

具有第 80 个字符自动换行等功能，易于视觉功能分组。理想情况下，文档编写者单独准备文档，然后将其注入或使用带有代码的 doxytags 链接。

此时我们正在使用记事本/IDE 来记录代码。

我有一个 Visual Studio (C#) 项目，其中启用了“XML 文档文件”属性。它还将“将警告视为错误”设置为全部。

有一个特定的类没有 XML 注释，它们不会被添加到其中。由于启用了 XML 文档和错误警告，这会导致构建失败。

当涉及到 XML 文档时，有没有办法忽略这个特定的类？

我将使用 Sandcastle 生成 API 文档 - 我在该网站上找不到任何有关如何执行此操作的指南。有没有人推荐任何快速入门指南？

我正在使用带有一些嵌入式 C 源的 Doxygen。给定一个 .c/.h 文件对，你是把 Doxygen 注释放在函数原型（.h 文件）还是函数定义（.c 文件）上，还是在两个地方都复制它们？

我有一个问题，当我在一个地方而不是另一个地方记录时，Doxygen 会警告缺少评论；这是预期的，还是我的 Doxygen 搞砸了？

还有谁让 Scitools 等工具了解 C++，哪个更好？

寻找适用于 Ada、C、C++ 和 Fortran 的最完整的自动文档工具。用于分析工具迁移工作，以帮助修剪死代码和识别基本功能。

皮特

我正在使用 Sandcastle Help File Builder GUI，我似乎无法在我的注释中获取代码示例以显示在帮助文件输出中。

我正在生成 Help 1.x 和 MSDN 样式的 HTML 文档。

这些示例在我的代码中如下所示：

我是否需要配置一些我不知道的项目属性？

哪些OSS（或免费）工具可用于起草可用于生成手册的文档的单一来源？具体来说，采用以下格式：

• HTML网站
• PDF文件
• 嵌入（在应用程序中；可能是 HTML）¹
• 文字（可选）
• 手册页（可选）

其他要求：

• 工具适合技术作家（不必是所见即所得）。
• XML/SGML 源
• 高质量的 PDF 输出（与 TeX 相媲美）
• 多平台

扩展要求¹

同一个命令行应用程序是用两种语言（C 和 Java）编写的。使用 XML 描述命令行选项（其中一些特定于一种语言或另一种语言），可以直接将 XML 转换为 Java 类或 C 函数，后者将帮助写入标准输出。这确保了帮助可以嵌入到二进制文件中，而不必依赖外部文件。

AsciiDoc 似乎没有这种能力。还有其他选择吗？