All geek questions in one place

Avoid Duplication in JavaDoc Comments

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

eg.

/** * 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 in case of an xml change, I have one resource for the change, and not for updating the entire JavaDoc for the affected methods.

Does anyone know how to do this?

+4
source share
5 answers

Why not read your documentation:

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

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

+4
source

How about using @see to link to another method?

+2
source

I would document (under pressure - in fact, I believe that documentation is a waste of time, since it is almost always wrong) uses tests to document your system) a CommonXML object, not every method that accepts an object of this type.

+1
source

You should not use Javadoc to repeat specifications defined elsewhere. Refer to the specification.

+1
source

You can use Doclava to enable or try a tag for this. These tags copy sample text from an arbitrary file to the javadoc html output file. The @include tag copies text verbatim from a given file. The @sample tag copies text from this file with some changes.

0
source

Source: https://habr.com/ru/post/1335609/

More articles:


All Articles