2

我在评论块中使用@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 视为“合法”的条目都将被标记为带有###前缀的“已删除”。

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

谢谢！

4

1 回答 1

5

（我是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条目在最终注释块中的放置位置。特殊元素<_/>用于指示应在何处插入空行。（原型是一种特殊的 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 网站每个页面的底部。我总是很乐意提供帮助。

于 2012-06-21T20:24:09.483 回答