问题标签 [documentation-generation]

我有一个 HTML 格式的常见问题解答（示例），其中的问题经常相互引用。这意味着每当我们插入/删除/重新排列问题时，编号都会改变。LaTeX 用 \label 和 \ref 非常优雅地解决了这个问题——你给项目简单的标签和 LaTeX 担心在最终文档中转换为数字。

人们如何在 HTML 中处理这个问题？

添加：请注意，如果您不必按编号实际引用项目，这没有问题，在这种情况下，您可以设置标签

<a name="foo">

然后链接到它

<a href="#foo">some non-numerical way to refer to foo</a>.

但我假设“foo”有一些自动生成的数字，比如来自一个<ol>列表，我想用那个数字来引用和链接它。

我想创建一个简单的中心文档，直观地显示我的 ASP.NET MVC 应用程序中的各种进程和依赖项，例如，当我的“Signup”操作方法获取 POST 数据、解密和验证发生时如何调用服务，最后一切都使用存储库存储，电子邮件服务会发送一封电子邮件。即使只是一个显示方法调用、实例名称和参数的流程图，从头到尾（带有分支）也会很棒。

有什么可以自动执行此操作的（例如，对于每个操作方法）还是你们手动执行/使用特定工具？它的全部意义在于让新开发人员快速了解应用程序中存在哪些类型的依赖项和流程，而无需对事物的工作方式进行无休止的“去定义”源内浏览。

谢谢

我很想问你开发dojo的人是如何创建文档的？

从每晚构建中，您可以获得包含所有注释的未压缩 js 文件，我确信有某种文档脚本可以从中生成一些 html 或 xml。

我猜他们使用 jsdoc，因为这可以在他们的 utils 文件夹中找到，但我不知道如何使用它。jsDoc 工具包使用/**commenting**/与原始 dojo 文件不同的符号。

感谢你的帮助

我在一家保险公司工作。我们有自己的开发部门，由近 150 人以及一些供应商（外包和定制应用程序）组成。在我们公司，我的团队制作了我们所说的非功能性逻辑库。也就是说，用于处理我们部门所有开发团队的横向事务的软件库，例如安全性、Web 服务、日志记录、消息传递等。大多数或这些工具要么是从头开始制作的，要么是根据实际标准改编的。例如，我们的记录器是一个基于 Log4J 的附加程序，它还将记录消息保存到数据库中。我们还定义了要在应用程序中使用的库，例如要使用的 Web 服务框架。我们在所有组织中都使用了很多 JavaEE 和 Oracle AS（带有一些 Websphere 应用程序服务器）。

这些项目中的大部分都记录了它们的体系结构（用例、UML 图等），并且通常可以使用生成的文档。现在我们看到的是，对于用户来说，有时很难使用我们提供的库，并且不断地提出问题，或者他们根本不使用它们。

所以我们计划为他们生成一个更友好的文档，所以我的问题是：软件文档应该有哪些最佳实践或清单？

我想到了一些东西：

1. API 参考指南
2. 快速入门教程
3. API 生成的文档。
4. 必须是可搜索的
5. 网络访问

它还应该有什么？此外，根据您的经验，维护（保持最新）和发布此类文档的最佳方式是什么？

这是先前关于 Sphinx的问题的通用版本。

有没有办法递归地自动记录包含类和函数的模块或包？

我认为为每个函数添加autofunctionor指令是愚蠢的；automodule必须有一种方法可以使该过程自动化，否则我根本看不到使用 Sphinx 的意义。

澄清： 而不是：

这需要我手动剪切和粘贴所有方法名称并相应地更新文档，我想要一个类似的命令：

我正在尝试将我们的数据库包更完整地记录为 API。我们想要的是类似于 JavaDocs for PL/SQL 的东西。我已经看到了一些工具（pldoc、plsqldoc），但想从使用它们的人那里了解它们的比较。

假设我有一个名为Color的 PHP 类，它的构造函数接受各种参数。

我应该如何使用 phpDoc 为构造函数和其他类似方法创建 API 文档？

如何使用带有重载方法的phpDoc？

是否有一个简单的文档系统，可以通过使用注释指示为任何语言生成一些友好的超链接文档？这样的系统可以仅仅被赋予正则表达式或模式来识别评论然后生成结构。

我本来打算写一篇，但想必已经有一篇了。

我有一个非常大的 .java 类文件，它有很多成员。如何为此创建 HTML 文档，以便按出现顺序向我显示成员，而不按成员类型排序？（方法、常量和变量）

例如，如果我的 Java 代码是：

Javadoc 按字母顺序排列成员并按类型排序，因此成员之间的关系丢失了：

此外，是否生成了具有更智能功能的文档？喜欢：

1. 提取方法和变量的附近注释
2. 方法的大小 - 代码行

哪个 Doxygen 选项可以完全禁用按类型（私有/公共/方法/变量）排序成员，并完全根据声明的顺序输出成员？