Search code examples
javadocumentationcommentsjavadoc

Avoiding duplication in JavaDoc comments

I am writing a class where the same xml is used between some methods.

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);

I would like to write my documentation so that if the xml changes I have one resource to modify, rather than updating all of the JavaDoc for the affected methods.

Does anyone know how to accomplish this?

Solution

  • Why not have your documentation read: 

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

    Then, if you update your XML, you just update your schema?