.NET 代码注释实用工具

• 下载可执行文件 - 121.4 KB
• 下载源代码 - 148.8 KB

引言

在我刚完成的 C# 框架中编写了一堆代码后，我决定深入研究 XML 注释我的代码。我做了一些 Google 搜索，以找出如何让它更轻松、更快。我遇到了许多实用工具。其中两个对我来说很突出，分别是 SandBlaster 和 GhostDoc。它们给了我一个很好的起点。Sandblaster 的优点在于它可以根据 Visual Studio 生成的 XML 文档生成帮助文件。GhostDoc 的优点在于可以在文档化方法、属性或其他代码块时生成一个基本框架。

问题是如何在文档中包含代码使用示例，就像您在 MSDN 网站上看到的那样。我可以创建 <example></example> XML 注释，但是没有简单的方法可以从代码的一部分复制代码片段并将其粘贴到 XML 文档文本的 <example> 部分。我做了更多的 Google 搜索，但没有找到任何可以帮助解决我的问题的东西。

在我的文档中包含示例代码对我的项目范围至关重要，但是尝试在 <example> 节点中间粘贴代码并进行格式化非常缓慢和繁琐。所以，我决定编写这个程序。

这个程序的目标很简单。

1. 使用此程序输入一些注释，然后让此程序生成 XML 代码，然后能够从此程序复制 XML 注释并将其粘贴到 Visual Studio IDE 中。
2. 反转 #1 过程。从 Visual Studio IDE 复制一个 XML 片段并将其粘贴到此程序的 XML 代码注释文本框中。然后删除行前缀字符 (///) 并生成纯文本以准备进行修改。
3. 在 XML 示例代码格式化程序窗口的注释文本文本框中输入一些描述示例代码作用的注释。然后从 Visual Studio IDE 复制一个代码片段并将其粘贴到代码文本文本框中。然后让此程序生成可以复制并粘贴到 Visual Studio IDE 中的 <example> XML 代码。
4. 反转 #3 过程。从 Visual Studio IDE 将 <example> 代码注释复制到 XML 示例代码格式化程序窗口的 XML 注释文本框中。然后单击“生成文本”按钮并删除所有行前缀字符 (///)，然后将代码返回到代码文本文本框和注释文本文本框中进行编辑。

背景

为了使用此程序，最好对 XML 文档有一个基本的了解。 MSDN 在这里有一些很好的信息。

使用软件

以下是使用此程序的一些技巧。

代码注释<-->注释文本

• 如果选中了“XML 注释”复选框，则注释文本不能包含任何特殊字符，例如“<>&”。这些是为内部 XML 标签保留的。此程序支持内部 XML 文档标签，并且允许这些特殊字符会混淆解析逻辑。（字符是 XML 标签的一部分还是不是？）如果您绝对需要这些字符，则需要手动将它们转换为 XML。有关更多信息，请参阅 www.w3schools.com/xml/xml_syntax.asp。
• 单击“生成代码注释”后，焦点将移至“代码注释”并选择所有内容。这样您就可以轻松按下 Ctrl+C 复制代码注释并将其粘贴到 IDE 中。
• 单击“生成注释文本”后，焦点将移至“注释文本”并选择所有内容，以便您可以修改文本。
• 单击“保存数据”将表单上的所有数据保存到注册表。

XML 示例代码格式化程序

• 注释文本不能包含任何特殊字符，例如“<>&”。这些是为内部 XML 标签保留的。此程序支持内部 XML 文档标签，并且允许这些特殊字符会混淆解析逻辑。（字符是 XML 标签的一部分还是不是？）如果您绝对需要这些字符，则需要将它们转换为 XML。有关更多信息，请参阅 www.w3schools.com/xml/xml_syntax.asp。
• 上述规则的例外是代码文本。由于假设代码块中不会有任何内部 XML，因此当生成 XML 注释时，它会将代码文本放在 XML 文档中，从而自动转换所有特殊字符。这可以防止代码在 Sandcastle 中引起帮助编译错误。
• 单击“生成 XML 注释”后，焦点将移至“XML 注释”并选择所有内容。这样您就可以轻松按下 Ctrl+C 复制代码注释并将其粘贴到 IDE 中。
• 单击“生成文本”后，焦点将移至“注释文本”并选择所有内容，以便您可以修改文本。
• 单击“保存数据”将表单上的所有数据保存到注册表。
• 重新格式化代码按钮 - 这是为了处理 Visual Studio IDE 的一些间距问题。我注意到在 Visual Studio 中，前导空格有时是空格和制表符的混合。当我将它们从 IDE 复制到代码文本时，我得到了一些非常古怪的代码。所以我添加了这个按钮，将代码文本文本框中的所有制表符 (\t) 字符替换为 4 个空格。这解决了大部分问题。

关注点

我学到了很多关于字符串操作和使用 LINQ 进行一些非常巧妙的字符串搜索的知识。以下是我在名为 GBLMethods 的静态类中创建的一些静态方法列表，以使过程顺利进行。有关这些方法的更多详细信息以及查看 Sandcastle 在处理此程序生成的 XML 文档后的输出，请参阅 Documentation.chm（包含在两个可下载文件中）。

方法名称	描述
CBool	将字符串变量安全地转换为布尔变量，不带任何异常。
CStr	将布尔变量转换为可以保存到数据库的字符串变量。
CInt	将字符串变量安全地转换为整型变量，不带任何异常。
SaveSetting	将值保存到注册表。
GetSetting	从注册表检索值。
WordWrap	将文本转换为行长不超过行长度的行。
IndentString	通过将文本拆分为以回车/换行符结尾的行来缩进字符串。然后它在每行的左侧放入行缩进字符串并返回字符串。
LeftStr, RightStr, MidStr	我从 www.csharphelp.com/2007/07/c-left-right-and-mid-functions/ 获得了这些方法。

历史

2015/03/19 - 初始发布