在 Atomineer 中修改规则

Question

我在我的评论块中使用了 @remarks 和 @ingroup，但是当我运行 Atomineer 时，它一直将它们标记为删除，我不知道如何防止它这样做。我查看了 .XML 配置文件中的修改规则，但我显然遗漏了一些东西。

使用 Atomineer 处理之前的示例：

//-------------------------------------------------------------------------------------
/// @copydoc interface_Result
///          
/// @ingroup platform_implementation module_core
//-------------------------------------------------------------------------------------

使用 Atomineer 处理后的示例：

//------------------------------------------------------------------------------------
/// @copydoc interface_Result.
///
/// ### ingroup platform_implementation module_core.
//------------------------------------------------------------------------------------

文档说：“设置您的 Doxygen 或 DocXML 模板，以指示新评论格式中的‘合法’条目，以及它们在新评论块中的排序方式。在旧格式和新格式中具有相同标签的任何条目（例如 param -> param）将自动“转换”（以新样式重新格式化）。任何不被 AtomineerUtils 视为“合法”的条目都将被标记为“已删除”，并带有 ### 前缀。”

任何指针或想法将不胜感激？我真的需要它来停止这样做。

谢谢！

Answer 1

（我是Atomineer Pro 文档的作者）

在 Visual Studio 中，

• 转到工具> Atomineer > Atomineer 选项...
• 切换到“高级自定义”选项卡
• 单击块模板 - Doxygen按钮。

将打开一个编辑器（记事本），其中包含供您自定义的模板。

这些模板是基于 XML 的，它们对 Atomineer 有指示：

• 哪些条目是合法的（必需或可选）。任何未提及的条目都被视为“非法”并根据您的发现予以删除。
• 生成/更新评论时条目的排序顺序
• 在注释块中放置额外空格（空行）的位置
• 其他一些事情，例如是否应为每个条目启用/禁用标点校正等

Atomineer 可以记录的每种不同类型的代码元素都有一个模板，因此您可以非常精确地控制文档的每个部分的外观，但这确实意味着您必须将新元素复制并粘贴到每个模板。

例如，这里是 Doxygen 方法注释的默认模板：

    <method>
        <prototype _punctuate="false" />
        <_ />
        <summary />
        <_ />
        <author _punctuate="false">%user%</author>
        <date _punctuate="false">%date%</date>
        <_ />
        <exception />
        <_ />
        <param />
        <_ />
        <returns />
        <_ />
        <sa _punctuate="false" _optional="true" />
    </method>

此中的每个 XML 元素（行）描述注释中的一个条目。例如，XML 标记<param/>对应于@param条目将放置在最终注释块中的位置。特殊元素<_/>用于指示应插入空行的位置。（prototype 是一种特殊的 doxygen，告诉它在哪里插入原型/声明 @fn、@class 等）

要允许@ingroup并@remarks插入 Atomineer 评论，只需在您希望它出现在评论中的位置为它们添加条目，如下所示：

    <method>
        <prototype _punctuate="false" />
        <ingroup _optional="true" /> 
        <_ />
        <summary />
        <_ />
        <remarks _optional="true" />
        <_ />
        <author _punctuate="false">%user%</author>
        ...
    </method>

您将看到我添加的示例元素中包含 属性_optional="true"。如果没有这个，Atomineer 会将该条目添加到每条评论中（必填条目）。如果设置为true，则Atomineer不会添加该条目，但如果您自己输入，则 Atomineer 将确保在您更新文档评论时保留它。

我很抱歉这太复杂了，但它是一个灵活的系统，允许每个人获得他们想要的东西，尽管有时需要几分钟的设置。每当我有时间时，我都会编写改进的配置工具和教程，以简化此过程。但是，一旦您配置好它，您应该会有很多快乐的时光;-)

此处有更多关于模板的文档以及您可以在其中执行的其他操作。

如果您还有其他问题，请随时在 Atomineer 网站每个页面底部的支持电子邮件中留言。我总是很乐意提供帮助。