Технические советы для написания замечательного Javadoc

Ответ 1

• Я бы сказал, что самыми важными являются @author, @deprecated, @inheritDoc, @param, @return, @throws. Но на всякий случай вы должны взглянуть на все теги.
• Мы используем @link при использовании в качестве объяснений внутри текста и @see в качестве списка ссылок.
• "Нужно ли использовать @param для очевидных параметров?" Нет.
• При необходимости используйте {@inheritDoc}.
• Вот список тегов.

Ответ 2

Я проводил свое исследование PhD по удобству использования JavaDocs, и мои результаты фактически противоречат "официальным рекомендациям", предоставленным Sun (полностью документируют и хорошо документируют), и обеспечивают поддержку "гибкого" подхода (напишите, что полезно).

Вкратце, проблема заключается в следующем: когда вы пишете все, вы, по сути, пишете спецификацию - подробные детали, которые позволят кому-то, кто "действительно заботится", узнать все о вашей функции и, возможно, написать полный план тестирования, Это важно во многих приложениях.

ОДНАКО, в сценариях повседневного развития ни один разработчик не собирается тратить свое время на чтение всего, что вы предоставили (я могу показать вам цифры на этом). Они собираются обезжирить, и они собираются пропустить информацию.

Часто то, что наиболее важно для общения, - это директивы - обычно делают и не выполняют инструкции, предостережения и другую "удивительную" информацию. Только некоторые методы передают их, и они часто теряются среди спецификаций.

При написании сложных JavaDocs вы эффективно скрываете важные директивы и уменьшаете вероятность того, что они будут потребляться. Пользователи также склонны избегать чтения JavaDocs, которые выглядят слишком долго.

Мой подход к этой проблеме заключается в явной пометке директив, поэтому пользователь, просматривающий JavaDocs, увидит их. У меня есть список тегов на моем сайте.

Я также разработал инструмент

Что касается того, о чем вы конкретно спрашивали: если вы идете с документированием всего, пойдите на основе спецификаций Sun, но это означает документирование даже очевидных вещей. Постарайтесь не добавлять HTML, так как это вредит читаемости без использования среды IDE. В книге "Чистый код" есть отличный раздел документации.

Вот те специальные теги, которые мы нашли необходимыми, просмотрев многие API:

use.restriction - запрещает использование метода из определенных контекстов (например, "не вызывать из потока пользовательского интерфейса" ) или определяет объекты, разрешенные для выполнения вызова (например, "для вызова только из инфраструктуры отладки" )

use.protocol - выдает последовательность вызовов. Например, "не вызывайте это перед вызовом X" или "не забудьте уведомить Y после вызова этого".

use.threading - передает некоторые проблемы, связанные с потоковой обработкой, например, требует использования системного потока или указывает, что выполнение может блокироваться.

use.locking - обеспечивает особые требования к блокировке

use.performance - передает клиенту, что с использованием этого метода возникает проблема с производительностью. Например, это занимает много времени

use.parameter - содержит специальные инструкции относительно возвращаемого значения, например обязанности по освобождению. Не используйте это для тривиальных вещей (используйте тег @param для них).

use.return - содержит специальные инструкции относительно возвращаемого значения, например обязанности по освобождению. Не используйте это для тривиальных вещей (используйте тег @return для них).

use.sideeffect - предупреждает пользователя о некотором побочном эффекте, связанном с вызовом этого метода

use.security - предупреждает пользователя о некоторых последствиях безопасности или требованиях, связанных с вызовом этого метода.

use.alternative - предоставляет пользователям возможность использовать другой метод. Например, "чтобы вызвать обновление, вызовите X вместо".

use.recommendation - предоставляет пользователям возможность выполнять дополнительные операции. Например, "вы можете сначала проверить URL-адрес".

use.limitation - предупреждает пользователя о некотором (неожиданном) ограничении в том, как работает этот метод. Например, "не сообщает изменения слушателям"

use.patternrole - передает пользователю, что метод или класс является частью шаблона. Редко используется.

use.association - передает пользователю, что метод или класс связаны с каким-либо другим объектом. Редко используется.

Ниже я вставляю фотографию того, как выглядит инструмент: в JavaDoc метода есть две помеченные вещи, и один из вызовов выделен, чтобы указать, что у него есть директива.

[EDIT: добавлена ​​(ниже) текстовая версия обновленного полного списка директив eMoose Javadoc из проекта .]

/*
@usage.general ...... No specific details
@usage.restriction .. Forbids the use of the method from certain contexts (e.g., "don't invoke from the UI thread") or defines the entities allowed to make the invocation (e.g., "To be called only from debug infrastructure")
@usage.protocol ..... Conveys some invocation sequence. For example "don't invoke this before you invoked X" or "remember to notify Y after calling this".
@usage.threading .... Conveys some issues relating to threading, such as requiring the use of a system thread or indicating that execution may block.
@usage.locking ...... Conveys specific locking requirements
@usage.performance .. Conveys to the client that there is some performance issue with using this method. For example, that it takes a lot of time
@usage.parameter .... Conveys specific instructions about the return value, such as deallocation responsibilities. Don't use this for trivial things (use the @param tag for those).
@usage.return ....... Conveys specific instructions about the return value, such as deallocation responsibilities. Don't use this for trivial things (use the @return tag for those).
@usage.sideeffect ... Alerts the user to some sideeffect associated with invoking this method
@usage.security ..... Alerts the user to some security implications or requirements associated with invoking this method.
@usage.alternative .. Conveys to the users that they may want to use a different method. For example, "to cause a refresh, call X instead".
@usage.recommendation Conveys to the users that they may want to perform additional operations. For example, "you may want to validate the URL first".
@usage.limitation ... Alerts the user to some (unexpected) limitation in how the method works. For example, "does not announce changes to listeners"
@usage.patternrole .. Conveys to the user that the method or class is part of a pattern. Rarely used.
@usage.association .. Conveys to the user that the method or class is associated with some other entity. Rarely used.
@todo.task .......... Indicates a remaining action item that would constitute an entire task (relevant primarily to full version)
@todo.step .......... Indicates a remaining item that would constitute a mere step in an entire task (relevant primarily to full version)
@todo.local ......... Indicates a small action item relevant to the current location. Essentially equivalent to a //todo comment
@todo.lookout ....... Indicates a need to be watchful for something in the future (relevant primarily to full version)
@todo.refactor ...... Indicates a need to refactor the material at the current location
@todo.optimize ...... Indicates a need to optimize the material at the current location.
@bug.general ........ General bug
@bug.task ........... Indicates a bug in the current task (relevant primarily to full version)
@bug.unrelated ...... Bug unrelated to current task (relevant primarily to full version)
@bug.resolved ....... Indicates that a bug has been resolved in this location
@bug.filed .......... Indicates that a certain bug (with given information) has been filed at this location
*/

Ответ 3

В дополнение к вашему конкретному вопросу, я бы рекомендовал вам всегда помнить, когда вы пишете свой javadoc аудиторию, на которую вы нацеливаете (пользователи API), и какие детали вы там ставите.

Необходимо указать поведение и НЕ детали реализации.

Для очень хорошего объяснения почему, кто лучше, чем эксперт по этому предмету, Джошуа Блох

Вот разговор Как создать хороший API и почему он имеет значение

Он немного длинный, но он того стоит.

С учетом этого вы можете написать полезный тег @return, который не пропустит детали реализации.

Ответ 4

Экспертная оценка.

Попробуйте найти кого-то вне вашей команды (клиента) и спросите их, что они думают о вашем JavaDoc.

Клиент всегда прав.

Ответ 5

Отличное чтение о написании javadoc находится на сайте sun at http://www.oracle.com/technetwork/java/javase/documentation/index-137868.html

Лучшее, что я узнал из этого текста, вероятно, что ваш уровень javadoc на уровне класса должен начинаться с "Обеспечивает". Это заставляет вас думать о том, что этот класс предоставляет вашей программе (или миру). Это не редкость для меня, чтобы перепроектировать программное обеспечение, потому что написание javadoc заставило меня подумать "эй, это здесь не нужно!".

Другие практические советы: когда интересен интерес, попробуйте записать его в теге @returns. Не делать этого может означать, что вы вводите материал дважды, один раз в javadoc и один раз после тега @return.

Лучший совет: если вы не знаете, что писать, DONT. парсер Javadoc делает отличную работу по автоматическому генерации getter javadoc, например, но это происходит только тогда, когда вы не добавляли /** */.

Javadoc должен описать, ЧТО ваш метод делает, а не КАК.

Джавадок не твой тодолист. Я пробовал, но для больших проектов это просто не работает.

Ответ 6

Я думаю, что, если вы не создаете библиотеку для широкого использования, не так уж много нужно для таких вещей, как @param (что часто бывает понятно из контекста и именования). На самом деле я нахожу их более сложными, чем не потому, что это то, что я могу забыть исправить на стадии рефакторинга.

Более полезными для меня являются такие вещи, как:

-Как работает ли функция в случаях краев? что он делает, если вы дадите ему нуль? Будет ли когда-нибудь возвращать нуль?

- В каких условиях он бросает это в список исключений

- Какие предположения он делает о состоянии входных объектов?

И снова это, вероятно, потому, что это те вещи, которые мне, как правило, нужно возвращать и проверять, и большинство написанных javadocs были либо для меня, либо для сотрудников небольших команд. Чем больше целевая аудитория, тем более строгий я бы чувствовал, что мне нужно быть.

Ответ 7

Еще один важный совет: если вы пишете абстрактный класс или интерфейс, обязательно визуально отделяйте текст для аудиторий, которые будут использовать метод для объектов из этой иерархии, и аудиторию, которая переопределит этот метод.

Слишком много фреймворков javadocs, которые представляют клиенты с самородками формы, "подклассы должны знать, что X...". Сделать это очень легко для подклассов, чтобы увидеть их, и для тех, кто не является подклассерами, чтобы их избежать. Никогда не смешивайте их без достаточного вертикального расстояния.

Ответ 8

В какой-то момент я провел немало исследований по этой проблеме, и я нашел документацию Javadoc по передовым методам беспорядочной и дезорганизованной. В частности, я обнаружил эти шесть ссылок из Sun (1 2 3 4 5 6). Мне кажется, что этот материал может быть лучше организован и сконденсирован каким-то образом.

Кроме того, как в стороне, HTML, который генерируется javadoc, плохо устарел. Это даже не действительный HTML. Я понимаю, что там есть javadoc doclets, но было бы неплохо увидеть официальную поддержку Sun. JavaFX имеет некоторые перспективные технологии документации, но не могу их использовать для кода Java, насколько я могу судить.