@since 的 DocBook 标签？答案

【问题标题】：DocBook tag for @since?@since 的 DocBook 标签？
【发布时间】：2014-01-27 02:40:40
【问题描述】：

DocBook 标准是否包含任何与 JavaDoc @since 标签等效的元素？

我专门尝试在“refentry”元素中执行此操作，但似乎没有什么合适的。

【问题讨论】：

标签： versioning javadoc docbook docbook-5

【解决方案1】：

我很确定 Javadoc @since 标记不存在语义等价物。 DocBook 的<refentry> 以手册页为模型，并且在 groff（man 宏）中也没有为此目的的特定标记，AFAIK。例如，mmap 手册页有几个“since”注释，它们简单地包含在 groff 源代码中，如下所示：

.BR MAP_32BIT " (since Linux 2.4.20, 2.6)"

dbdoclet 是将 Javadoc 转换为 DocBook XML 的工具。对于在其顶级文档注释中具有 @since 标记的类，它会输出如下标记：

<variablelist>
    <varlistentry>
      <term><emphasis>Since</emphasis></term>
      <listitem>
        <para><simplelist type="inline"><member>January 8, 2014</member></simplelist></para>
      </listitem>
    </varlistentry>
</variablelist>

这并没有什么“错误”，但它相当冗长。

我建议保持简单。只需将“since”信息添加到任何看起来合适的标记容器中。例如：

refsection 的标题：

<refsection>
   <title>TITLE HERE (since release X.Y.Z)</title>
    ...
</refsection>

一个段落（可能带有role 属性）：

<para role="since">Since release X.Y.Z</para>

【讨论】：

是的，这就是我最终要做的事情。困扰我的不是语义，但我可以忍受。

【解决方案2】：

也许标签revhistory和子标签revision，可以用于它。

下面是一个捕捉这个想法的小例子：

<section  title="Section with history information">
  <revhistory>
    <revision>
      <revnumber>0.9</revnumber>
      <date>1996-12-11</date>
    </revision>
  </revhistory>

  <para>
    <revhistory>
      <revision>
        <revnumber>0.8</revnumber>
        <date>1996-11-11</date>
      </revision>
    </revhistory>
    This paragraph has it's own revision history.
  </para>
</section>

【讨论】：

我尝试了这种方法，但它确实是矫枉过正。有一些项目将 JavaDoc 转换为 DocBook，我想我可能会看看他们做了什么。