问题标签 [code-documentation]

您的 .NET 源代码中有多少代码文档太多了？

一些背景：我继承了我在 SO 上发布的其他一些问题中谈到的大型代码库。该代码库的“特性”之一是 God Class，它是一个具有超过 3000 行代码的单个静态类，包含几十个静态方法。这是从Utilities.CalculateFYBasedOnMonth()到Utilities.GetSharePointUserInfo()到的一切Utilities.IsUserIE6()。这都是不需要重写的好代码，只需重构为一组适当的库。我已经计划好了。

由于这些方法正在进入一个新的业务层，而我在这个项目中的角色是准备系统以供其他开发人员维护，我正在考虑可靠的代码文档。尽管这些方法都具有良好的内联注释，但它们并不都具有 XML 注释形式的良好（或任何）代码文档。使用 GhostDoc 和 Sandcastle（或 Document X）的组合，我可以创建一些非常漂亮的 HTML 文档并将其发布到 SharePoint，这将使开发人员无需浏览代码本身就可以更多地了解代码的作用。

随着代码中文档数量的增加，导航代码变得越困难。我开始怀疑 XML 注释是否会使代码更难维护，比方说，//comment每个方法都更简单。

这些示例来自 Document X 示例：

和：

所以我想问您：您是否使用 XML 注释来记录您的所有代码，目的是使用 NDoc (RIP) 或 Sandcastle 之类的东西？如果没有，您如何决定哪些获取文档，哪些不获取？像 API 之类的东西显然会有 doco，但是你要交给另一个团队来维护的代码库呢？

你觉得我应该怎么做？

我对 PHP dockblocks 非常熟悉，因为过去 15 年多来我一直在从事这项工作。

我想了解的是是否有像 Delphi 和/或 FreePascal 这样的标准。

根据我对大量代码的分析，我从未见过任何代码，但我可能大错特错。

我们在我们的产品中使用 java 6 脚本引擎，现在我们正在考虑添加一些调试功能。

我的问题是：

1. 可能吗？就调试而言，java 6 脚本引擎是否具有与 rhino 相同的功能。
2. 一些关于如何开始做的文档，一些代码示例任何信息都会很棒，因为我在网上找不到任何东西。

谢谢

我们正在管理一个 C++/C# 库，我们注意到许多类和函数没有记录在案。

我们考虑编写一个脚本来解析代码以查找未记录的类和方法以生成未记录的类/方法/函数的列表。

我们还希望将 dOxygen 标记放置在缺少文档的位置的脚本。即如果找到这样的代码：

它将被替换为

当然，如果该函数将来有一个自动生成的文档标题但没有人触及该标题，它仍然会在报告中报告为未记录。

您将使用哪种脚本语言来开发这样的工具？

安东尼

可能重复：
自动生成 PHP 文档？

我是 PHP 新手，我目前的工作要求我以极快的速度学习这门语言。

我是一个文档坚持者。我什至喜欢写文档。我熟悉几种语言的公认文档语法和工具。

这不是 PHP 的情况。

我知道编写可文档化的源代码注释总是有多种方法，并且每种语言通常都有各种工具。但是，我所处的环境没有规定标准的评论方式，也没有标准的 PHP autodoc 工具。这给了我选择的自由，并伴随着一些分析瘫痪。

phpDocumentor ( http://www.phpdoc.org/ ) 是 PHP 自动文档可接受的标准工具吗？

在记录 PHP 代码时是否可以遵循代码的一般 JavaDoc 准则？

对于项目中的每个类，SandCastle 创建（其中包括）两个页面：

• 主页，称为T_class_full_name，带有描述、语法、继承层次结构和另见
• 成员页面，称为AllMembers_T_class_full_name，带有构造函数、方法、字段等。

有没有办法将这两者合并在一起 -members page附加到主页？

如何强制 Doxygen 显示完整的包含路径？

我是什么意思：

我在以下目录结构中foo::bar::bee定义了一个类：bee.hpp

Doxygen，当它记录foo::bar::bee类时告诉你需要包含<bee.hpp>，但对于我的软件我需要<foo/bar/bee.hpp>

我怎样才能让 Doxygen 做到这一点？是否有任何选项可以提供“-I”之类的“包含标志”，以便 doxygen 知道基地在哪里？

笔记：

• FULL_PATH_NAMES已设置为默认值YES
• 我不想为每个类明确地提供包含头，因为它们太多了。我希望 Doxygen 自动执行此操作。

谢谢。

回答

放：

我们向外部客户提供了许多程序集，但并非所有公共 API 都得到官方支持。例如，由于不是最优的设计选择，有时必须从程序集中公开一个类型才能使我们的其余代码正常工作，但我们不希望客户使用该类型。沟通缺乏支持的一部分是不以 XML 注释的形式提供任何智能感知。

有没有办法选择性地抑制 XML 注释？我正在寻找除了忽略警告 1591 之外的其他东西，因为它是一个长期维护问题。

示例：我有一个包含公共类 A 和 B 的程序集。A 得到官方支持，应该有 XML 文档。B 不适用于外部使用，不应记录在案。我可以打开 XML 文档，然后取消警告 1591。但是当我稍后添加官方支持的 C 类时，我希望编译器告诉我我搞砸了并且未能添加 XML 文档。如果我在项目级别取消了 1591，则不会发生这种情况。我想我可以跨整个班级#pragma，但似乎应该有更好的方法来做到这一点。

更改 UILabel 颜色的语法是什么？

另外，在哪里可以找到这些信息？

您知道有一种工具可以轻松地为 JavaScript 和 PHP 代码创建文档吗？

在类似于下图的代码中接受注释的东西：

并将这些转换为 HTML 文件（可能在左侧带有框架集菜单）。 不需要上面显示的相同语法，这只是一个解释我在说什么的例子。

只想要一个工具，所以一旦我学会了编写文档的语法，我就可以对 PHP 和 JavaScript 使用相同的文档语法。

如果该工具是二进制 (.exe) 或 Java 代码，无需安装 PERL 或 PYTHON，那就太好了。