xml - 在 Atomineer 中修改规则

Question

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

使用 Atomineer 处理之前的示例:

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

使用 Atomineer 处理后的示例:

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

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

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

谢谢!

Answer 1

(我是 Atomineer Pro Documentation 的作者)

在 Visual Studio 中，

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

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

模板是基于 XML 的，它们指示 Atomineer:

• 哪些条目是合法的(必填或可选)。任何未提及的条目都将被视为“非法”并在您找到后删除。
• 生成/更新评论时条目的排序顺序
• 在评论 block 中放置额外空格(空行)的位置
• 其他一些事情，比如是否应该为每个条目启用/禁用标点符号校正等

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，告诉它在哪里插入原型(prototype)/声明 @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 将确保在您更新文档注释时保留它。

对于这其中的复杂性，我深表歉意，但这是一个灵活的系统，允许每个人得到他们想要的东西，尽管有时需要几分钟的设置。只要有时间，我就会编写改进的配置工具和教程，以简化此过程。不过，一旦你配置好了它，你应该会有许多快乐的岁月;-)

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

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