避免JavaDoc注释中的重复

Question

我正在编写一个类，其中在某些方法之间使用相同的xml。

e.g。

/**
 * Sample Response:
 * <xmp>
 *      <myXML>
 *          <stuff> data </stuff>
 *      </myXML>
 * </xmp>
 */
 CommonXML Method1();

/**
 * Sample Submission:
 * <xmp>
 *      <myXML>
 *          <stuff> data </stuff>
 *      </myXML>
 * </xmp>
 */
 void Method2(CommonXML xml);

我想编写我的文档，以便在xml更改时我有一个资源需要修改，而不是更新所有受影响方法的JavaDoc。

有谁知道如何做到这一点？

Answer 1

为什么不阅读您的文档：

/**
 * Returns an XML file conforming to the CommonXML schema, available here 
 * (link-to-schema).
 **/

然后，如果您更新XML，只需更新架构？

Answer 2

使用@see引用其他方法怎么样？

Answer 3

我会记录（在胁迫下 - 实际上我认为文档是浪费时间，因为它几乎总是错误的 - 使用测试来记录你的系统所做的事情）CommonXML对象，而不是采用这种类型的对象的每个方法

Answer 4

您不应该使用Javadoc重复其他地方定义的规范。 请参阅规范。

Answer 5

您可以使用Doclava的include or sample tag来执行此操作。这些标签将示例文本从任意文件复制到输出javadoc html中。 @include标记从给定文件中逐字复制文本。 @sample标记通过一些修改复制给定文件中的文本。