Atomineer Pro Documentation 10.30

Visual Studio 的Atomineer Pro 文档
很荣幸成为 Visual Studio Sim-Ship 合作伙伴！

Visual Studio 发布合作伙伴Visual Studio 的这个扩展提供了无与伦比的代码文档注释生成和更新、注释中文本的智能自动换行、实时输入帮助使编辑注释变得更加容易、快速将旧文档转换为新格式的工具、即时对齐代码的命令（例如作为分配、参数和表格数据）到列中，以及几个方便的大纲、代码生成和剪贴板命令。

（这个怎么运作）
省时-省力-省钱。
消除填写文件的繁琐工作。
轻松保持代码和文档同步。
鼓励更好的编码、命名和文档实践。
借助您自己的所有类和方法的智能感知帮助加快开发并减少错误。
轻松满足文档的代码分析和静态分析要求。
在您编辑评论时，通过自动格式化、自动换行、粘贴和项目符号列表输入辅助以及实时拼写检查来加速评论的编辑。

详细功能- 文档代码：更好、更快、更整洁、更便宜
使用单个按键或菜单命令，扩展程序可以：

创建或更新高度可配置的文档 XML、 Doxygen、 Qt QDoc、 JavaDoc或 Natural Docs -代码中代码元素（文件、命名空间、类、接口、模板、结构、枚举、变量、属性、事件、委托、函数/方法等）的格式文档注释。Atomineer 将自动为您的文档生成一个清晰的起点，为所有参数、泛型类型参数、抛出的异常和返回代码提供上下文相关的描述，使用上下文信息，例如相关基类的现有文档和覆盖方法/属性和现有参数在同一个类中，并为数以千计的常见函数、类和参数类型生成准确和专门的文档。注释可以在所有支持的格式和定制格式之间自动转换，以将旧文档更新为新标准。它还可以选择使用自动缩进、自动换行和 XML 验证/更正来重新格式化更新的文本，以使您的代码文档保持合法、准确、信息丰富和整洁，而您只需付出最少的努力。对于任何希望编写可维护代码的团队来说，这是一个绝对必要的工具。
自动记录/转换命名空间/接口/类/结构/枚举范围内的每个代码元素。
在块注释中自动换行文本。
立即将相似的代码行（例如分配、参数等）对齐到列中，以提高清晰度、可读性和可编辑性。
使用 Visual Studio 的大纲工具隐藏所有文档注释和/或属性声明。
从声明（在标头中）自动生成 C++/C 框架实现（在源文件中）。
打开给定 C++ 源文件的匹配头文件，或给定头文件的匹配源文件。
将 C++/C 声明添加到任何现有方法实现的标头中。
从成员变量声明创建 C# 自动属性、显式属性或 C++ 访问器函数。
以干净的格式将代码复制到剪贴板，非常适合在编写 Word .doc 文档或通过电子邮件将示例发送给团队成员等应用程序中使用。

代码文档- 为什么要这样做？
编程时，了解类和方法的用途，如何使用它们以及它们如何工作对于快速开发/维护和避免由于误解而导致的错误至关重要。把这些信息写下来很重要——在团队之间分享这些知识，以及让程序员回忆他们很久没有接触过的代码的细节。

许多程序员编写“自我记录”代码，其中清晰和描述性的命名约定使得更容易快速理解代码。文档注释通过在一个地方总结这些信息而更进一步，而不必通读通常非常复杂的源代码。此外，最重要的是，代码文档可以告诉您“自我记录”代码从未提及的事情：

方法会抛出什么异常？
我可以将 null 传递给此参数吗？
整数参数的合法范围是多少？
描述“未找到”的返回值是什么？
编写“自我记录”代码只是编写有据可查、可维护的代码的第一步，也是最基本的步骤。

此外，Visual Studio 的 Intellisense 系统可以使用来自文档注释的信息，当您键入客户端代码时，您需要的信息会实时显示在工具提示中。

还有一些工具，如 Doxygen（所有语言）和 SandCastle（.NET 语言），可用于生成专业的外部文档，如 MSDN 中使用的文档——对于将要发送给第三方的库和其他代码以及对您的团队内部使用非常有用。

只有三个问题：

编写文档可能非常耗时
程序员通常更喜欢编写代码，因此文档（如果有的话）会受到影响
注释很容易与代码“不同步”，使它们无用甚至误导
Atomineer 消除了这些问题：

它最大限度地减少了文档编制所涉及的工作量。大部分文档内容是重复的，很容易被计算机填写。尽管您经常需要在 Atomineer 提供的评论中添加内容，但它会立即为您的评论奠定坚实的基础。
它以标准化的形式总结了尽可能多的关于代码元素的信息，使其成为一种快速阅读的格式，无论是哪个程序员编写的代码。
它使文档与代码的更改保持同步（例如，当方法中的参数、返回值或抛出的异常发生更改，或者将 get/set 访问器添加到属性时）。
在许多语言中， Visual Studio 会拾取XML 文档 注释，并在您键入方法调用时在智能感知工具提示中显示，这使得编写代码更容易、更快且更不容易出错。
Atomineer比任何类似的扩展都走得更远——它通过强制换行、调整格式和元素排序、缩进、标点符号和自动换行来保持文档和周围代码的整洁——它代表你努力保持注释的整洁和可读性。所有这些选项都是可配置的，因此很容易确保所有评论都是您需要的精确样式。
使用 Atomineer 的团队经常发现，该扩展在整个团队中积极促进更一致的命名实践，因为良好的命名为文档提供了更好的起点。
它鼓励开发人员编写文档并使其保持最新。程序员想要编写代码，而 AtomineerUtils 允许专注于他们喜欢的事情，同时仍然可以制作出色的文档。
与单元测试类似，编写文档鼓励程序员更多地思考他们的代码以及其他人将如何使用它。这通常会导致相关代码中改进的设计和更低的缺陷率。
通常，Atomineer 开发人员每年仅在制作文档时就可以节省大约 1-2 个工作周 - 即使在我们考虑不太明显的下游时间节省和质量优势之前，这也是巨大的成本节省。

为什么选择Atomineer？
Atomineer Pro 文档不是简单地重复使用基本单词重新排序的代码元素的名称。它使用数千条规则来尝试根据命名、类型、上下文和现有文档（例如，在类或其基类中）生成最有意义的文档。

以下是 Atomineer 将纯粹根据参数的名称和类型生成的一些注释示例：

范围    自动生成的文档
字符 *serialIOBuff    [in,out] 如果非空，则为串行 i/o 数据缓冲区。
字符串用户信息    描述用户的信息。
IdGroup programIds    程序的标识符列表。
CString config_fname    配置文件的文件名。
整数进程索引    进程的从零开始的索引。
参数对象[] fmtValues    包含格式值的可变长度参数列表。
有关类、方法、参数和返回类型的更多示例，请参阅： 文档 XML 格式注释 和Doxygen 格式注释。

...并且 Atomineer 并不止于文档生成 - 它包括许多特殊功能，可帮助您创建和维护文档注释，例如复制现有文档、提供实时输入辅助以加快注释速度、拼写检查以提高注释质量，自动换行和重新格式化工具以保持评论整洁，以及实时预览窗口，让您可以更轻松地阅读文档。