Avoiding duplication in JavaDoc comments

Question

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?

I guess you can specify one class to create it's java-doc. need to Google though. :) — Nishant, Jan 14 '11 at 20:55
I think wanting to re-use variable definitions in Javadoc is a common problem. The fact the OP here asks about an XML document hides how common it is - see http://stackoverflow.com/questions/7021696/javadoc-reusable-parameter-values and http://stackoverflow.com/questions/1036565/is-it-possible-to-re-use-param-descriptions-in-javadoc — Mark Butler, Feb 13 '13 at 15:39

JohnnyO · Accepted Answer · 2012-01-13T19:03:27.597

4

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?

edited Jan 13 '12 at 19:03

answered Jan 14 '11 at 20:53

JohnnyO

3,018
18
30

1

You should end the sentence with a period per the JavaDoc guidelines. – Steve Kuo Jan 14 '11 at 21:42

score 2 · Answer 2 · answered Jan 14 '11 at 20:55

2

What about using @see to refer to the other method?

answered Jan 14 '11 at 20:55

score 2 · Answer 3 · answered Jan 14 '11 at 20:57

2

I would document (under duress - actually i think documentation is a waste of time, as its almost always wrong - use tests to document what your system does) the CommonXML object, rather than each method that takes an object of this type.

answered Jan 14 '11 at 20:57

time4tea

2,169
3
16
21

+1 for the suggestion to document the CommonXML object (and almost a -1 for thinking documentation is a waste of time.. nothing is more frustrating that debugging code that isn't documented.. reading tests to figure out what the code is supposed to do is far more time-consuming.. documentation is a first-class duty of a developer!) – jk. Jan 14 '11 at 21:02
1

As 90% of developers time is allegedly spent reading code, i prefer to spend the "documentation" time refactoring the code, so that its really easy to understand. However i understand that people have strongly held views on that kind of thing! – time4tea Jan 14 '11 at 21:12
The comments are used by consumers of what I produce, so relying on code is not a solution I can work with. – TERACytE Jan 14 '11 at 22:35

score 1 · Answer 4 · answered Jan 15 '11 at 00:34

1

You shouldn't be using Javadoc to repeat specifications that are defined elsewhere. Refer to the specification.

answered Jan 15 '11 at 00:34

user207421

305,947
44
307
483

score 0 · Answer 5 · answered Feb 13 '13 at 15:59

You could use Doclava's include or sample tag to do this. These tags copy sample text from an arbitrary file into the output javadoc html. The @include tag copies the text verbatim from the given file. The @sample tag copies the text from the given file with some modifications.

Avoiding duplication in JavaDoc comments

5 Answers5