Как избежать дублирования в комментариях JavaDoc

Question

Я пишу класс, в котором между некоторыми методами используется один и тот же xml.

Например,

/**
 * 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

Вы не должны использовать Javadoc для повторения спецификаций, которые определены в другом месте. См. к спецификации.

Answer 4

Я бы задокументировал (под принуждением - на самом деле я думаю, что документирование - пустая трата времени, поскольку его почти всегда неправильно - использовать тесты для документирования того, что делает ваша система) объект CommonXML, а не каждый метод, который принимает объект этого типа.

Answer 5

Вы можете использовать Doclava 's include или образец тега для этого. Эти теги копируют образец текста из произвольного файла в выходной HTML-файл Javadoc. Тег @include дословно копирует текст из данного файла. Тег @sample копирует текст из данного файла с некоторыми изменениями.