Есть ли способ прикрепить комментарий документа Javadoc к сценарию Groovy?

Для класса или метода Groovy или Java я бы обычно включал любую документацию на уровне API в комментарий документа (он же комментарий Javadoc), а не в обычный комментарий. Каков аналогичный способ добавления таких комментариев к сценарию Groovy?

Меня лично не очень волнует, подберет ли инструмент Javadoc документацию. Однако документация о назначении скрипта Groovy кажется концептуально аналогичной документальному комментарию к классу; поэтому я интуитивно ожидаю, что они будут в комментарии к документу. Если моя интуиция неверна и теги документа не являются стандартным способом комментирования смысла сценария Groovy, какой является предпочтительным методом документирования назначения сценария?


person M. Justin    schedule 05.11.2015    source источник


Ответы (1)


раздел синтаксиса спецификации языка Groovy определяет элементы, которые может использовать комментарий Groovydoc. быть связанным с:

Комментарии [Groovydoc] связаны с:

  • определения типов (классы, интерфейсы, перечисления, аннотации),
  • определения полей и свойств
  • определения методов

Хотя компилятор не будет жаловаться на то, что комментарии Groovydoc не связаны с вышеперечисленными языковыми элементами, вы должны добавить комментарий к этим конструкциям прямо перед ними.

Сценарий не имеет определения типа класса, чтобы поместить комментарий Groovydoc перед ним.

Существует открытая проблема с запросом этой функции в средстве отслеживания проблем Groovy по адресу GROOVY-8877:

Groovydoc не предлагает прямого способа документирования сценариев Groovy. Он будет обрабатывать комментарии к классам в скрипте Groovy, но не любые комментарии на уровне файла или на верхнем уровне.

Таким образом, комментарии Groovydoc на уровне сценария в настоящее время не поддерживаются в файле сценария Groovy.

person M. Justin    schedule 06.11.2015
comment
Это, к сожалению, все еще так. Я могу сгенерировать документы для функций в моем скрипте, но в верхней части нет ничего, что могло бы описать скрипт. - person Levi; 27.08.2020