Разное

Как пользоваться javadoc: Документирование кода javadoc

Содержание

Как увидеть JavaDoc в IntelliJ идее?



Я только что переключился с Eclipse на IntelliJ. IntelliJ не хватает одной функции из Eclipse - когда вы наводите курсор мыши на метод, Eclipse показывает информацию javadoc. Я думаю, что способ показать это-использовать ярлык- command + J, но когда я нажимаю на него, я получаю что-то неправильное, как на снимке экрана ниже. Пожалуйста, посоветуйте мне, как я могу быстро получить информацию о javadoc. Мне нужно, по крайней мере, знать, какой тип возвращает метод.

java intellij-idea ide javadoc
Поделиться Источник Eugene     15 июня 2012 в 14:56

11 ответов


  • Как отключить демон Gradle в идее IntelliJ?

    Мне нужно отключить демон Gradle в идее IntelliJ, потому что каким-то образом плагин Scala не работает с демоном (компиляция завершается неудачей с NullPointerException ). Я попытался отредактировать свои конфигурации сборки IntelliJ Gradle, чтобы включить системный параметр JVM...

  • Можно ли написать lambda букву (λ) в IntelliJ идее?

    Я хотел бы использовать этот интерфейс: http:/ / javaslang. com/javadoc/2.0.0-RC2/javaslang / %CE%BB.html К счастью, автоматическое завершение работает, если я начинаю с имени пакета. Но можно ли написать ламду греческой буквой в IntelliJ идее или вообще в любом редакторе?



673

Используйте View / Quick Documentation или соответствующую комбинацию клавиш (по умолчанию: Ctrl + Q на Windows/Linux и Ctrl + J на macOS или F1 в последних версиях IDE). Дополнительные сведения см. В документации .

Также можно включить автоматическое всплывающее окно JavaDoc при явном (вызываемом ярлыком) завершении кода в Settings | Editor | General | Code completion (документация Autopopup ):

Еще один способ увидеть быстрый док-это движение мыши :

Поделиться CrazyCoder     15 июня 2012 в 15:08



140

Перейдите к File/Settings , Editor, нажмите на General . + j не + j )

Поделиться Dropout     18 сентября 2013 в 09:01


  • F4 ярлык в myeclipse и его эквиваленты в IntelliJ идее

    В MyEclipse , F4 ярлык используется для поиска классов, которые extends/implements/override текущего типа, например Class/Interface/method . Этот ярлык полезен для меня. По идее IntelliJ вышеуказанного кредитного добиться, слева зеленый значок class/interface/method. Это означает, что я должен...

  • IntelliJ JavaDoc @see

    Я довольно новичок в IntelliJ. Мой IntelliJ не выделяет @see в комментариях. Похоже, что IntelliJ не видит @see как ключевое слово JavaDoc, но я не могу понять, как это изменить. Это нормально или я могу исправить эту проблему?



24

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

IntelliJ 14

Редактор / Общие сведения - > показать быструю документацию при перемещении мыши

Более старые версии

Добавьте следующую строку в файл idea.properties:

auto.show.quick.doc=true

Поделиться Michal Z m u d a     11 ноября 2013 в 13:23



8

Конфигурация для IntelliJ IDEA CE 2016.3.4 для включения JavaDocs при наведении мыши. Я запускаю IntelliJ IDEA на Mac OS, но считаю, что Linux/Windows должен иметь аналогичные опции.

Autopopup docs: IntelliJ IDEA > Preferences > Editor

> General > Code Completion

Документация по перемещению мыши: IntelliJ IDEA > Preferences > Editor > General

NOTE: Пожалуйста, нажмите кнопку Применить , чтобы применить эти настройки

Поделиться realPK     06 марта 2017 в 01:18



5

Чтобы обеспечить наилучшую функциональность зеркальных затмений, Включите следующие настройки:

  • IDE настройки / редактор - > Other. Show быстрый документ при перемещении мыши
  • IDE Settings/Editor/Code Завершение - > Документация Autopopup

Чтобы увидеть javadoc в меню автозаполнения, нажмите".", чтобы получить всплывающее окно, а затем наведите курсор на объект, с которым вы работаете, как только вы получите всплывающее окно javadoc, вы можете выбрать элемент во всплывающем окне, чтобы переключить javadoc. Не идеально... Но это что-то.

В качестве еще одной записки. Функция поиска в меню опций очень полезна. Просто введите 'doc', и вы увидите все варианты doc.

Кроме того, поиск "autopopup doc" не только найдет каждый из вариантов, но и выделит их в меню. Очень круто!


Edit: выходя за рамки первоначального вопроса, это может быть полезно для людей, которые просто хотят получить быстрый и легкий доступ к документам.

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

Лично Ctrl+Q на windows не был идеальным, поэтому я переназначил его на Alt+D. Переназначение можно выполнить в разделе IDE Settings/Keymap. один раз в меню keymap, просто найдите быструю документацию.

Поделиться J.D.     03 сентября 2014 в 04:55


Поделиться ROMANIA_engineer     19 сентября 2015 в 21:28



4

Перейдите в Настройки -> редактор - > общие , а затем включите функцию Показать быструю документацию при перемещении мыши

Поделиться Vork     12 февраля 2015 в 01:10



4

Для меня это было не просто открытие окна javadoc, но и полное представление javadoc. Вы все еще можете получить разреженный javadoc, основанный исключительно на сигнатуре метода, если вы импортируете библиотеки из репозитория Maven и не говорите Idea включить javadoc в загрузку. Обязательно отметьте опцию "JavaDocs" в диалоговом окне "Download Library From Maven Repository", которое можно найти в разделе Структура проекта -> настройки проекта -> Библиотеки.

Поделиться Craig Lowery     31 января 2016 в 22:46



2

Наиболее близким к Eclipse будет клавишу Ctrl+щелкните элемент button2 (прокрутка пункт)

Это называется Quick Doc в IntelliJ, я хочу, чтобы ребята из JetBrains однажды добавили quick doc, как Eclipse, с помощью Ctrl+Mouse Move , это намного лучше.

В моем случае только с одним движением мыши немного раздражает, поэтому, если вы поищете в настройках / настройках --> Keymap for "quick documentation", вы найдете:

  • Win-Linux: "Ctrl+Q" и "Ctrl+Button2 Click" (прокрутка щелчка)
  • Mac: "Ctrl+J" и "Ctrl+Button2 Click" (Scroll click)

Поделиться r1ckr     06 мая 2015 в 15:50



1

Я заметил, что выбор имени метода и нажатие клавиши F2 (быстрая документация) выводит его на JavaDoc.

Я использую Intellij 2016 и Eclipse Keymap

Поделиться razvang     25 мая 2016 в 15:24


Похожие вопросы:


Как создать проект OSGI в идее IntelliJ?

Я пытаюсь создать проект OSGI по идее IntelliJ, но до сих пор не смог этого сделать. Я могу изменить фасет после создания проекта Java, но это не тот, который мне нужен. В eclipse, пока я создаю...


Intellij IDEA автоматически показывает javadoc

Когда я кодирую в Netbeans, он автоматически заполняет код и показывает Javadocs. Однако, когда я использую Intellij IDEA если я нажимаю Ctrl + Space я вижу автозаполнения и если я нажимаю Ctrl + Q...


Изображения в JavaDoc с IntelliJ идеей

Я пытаюсь включить изображения в свой JavaDoc. Я следую документации и храню изображение в doc-files в каталоге пакетов. Мой javadoc выглядит так: /** * This is class desctiprion. Image: *...


Как отключить демон Gradle в идее IntelliJ?

Мне нужно отключить демон Gradle в идее IntelliJ, потому что каким-то образом плагин Scala не работает с демоном (компиляция завершается неудачей с NullPointerException ). Я попытался...


Можно ли написать lambda букву (λ) в IntelliJ идее?

Я хотел бы использовать этот интерфейс: http:/ / javaslang. com/javadoc/2.0.0-RC2/javaslang / %CE%BB.html К счастью, автоматическое завершение работает, если я начинаю с имени пакета. Но можно ли...


F4 ярлык в myeclipse и его эквиваленты в IntelliJ идее

В MyEclipse , F4 ярлык используется для поиска классов, которые extends/implements/override текущего типа, например Class/Interface/method . Этот ярлык полезен для меня. По идее IntelliJ...


IntelliJ JavaDoc @see

Я довольно новичок в IntelliJ. Мой IntelliJ не выделяет @see в комментариях. Похоже, что IntelliJ не видит @see как ключевое слово JavaDoc, но я не могу понять, как это изменить. Это нормально или я...


Как сделать так, чтобы IntelliJ отображал Javadoc предложений по автозаполнению?

IntelliJ отображение предложений по автозавершению кода Java в раскрывающемся меню после нажатия кнопки Ctrl Space . Все остальные IDEs управления для отображения соответствующей документации, если...


Как установить javadoc внешних библиотек в IntelliJ Idea?

В IntelliJ Idea я установил автономный javadoc Java SDK в структуре проекта -> SDKs - > пути документации и добавил путь к папке документации. Всякий раз, когда я хочу увидеть всплывающую подсказку,...


Javadoc не генерируется автоматически в идее IntelliJ

У меня возникли проблемы с шаблонами файлов для разработки Java в IntelliJ IDEA. Я создал файл includes для анализа и создания комментариев Javadoc из него. Файл > Настройки > редактор > Шаблоны...

Документация Kotlin кода - Kotlin

Язык для документации Kotlin кода (являющийся аналогом Java JavaDoc) называется KDoc. По сути, KDoc комбинирует JavaDoc синтаксис для тегов (расширенных для поддержки специфичных Kotlin конструкций) и Markdown для встроенной разметки.

Генерация документации

Утилита для генерации Kotlin документации называется Dokka. Смотрите инструкцию по использованию Dokka README.

В Dokka есть плагины для Gradle, Maven и Ant, поэтому вы можете интегрировать создание документации в свой процесс сборки.

KDoc синтаксис

Как и JavaDoc, KDoc комментарий начинается с /** и заканчивается */. Каждая линия комментария может начинаться со звездочек, которые не считаются частью содержимого комментария.

Обычно первый параграф текста документации (параграф считается первым до первой пустой строки) - это общее описание элемента, а текст дальше является детальным описанием элемента.

Каждый тег начинается с новой строки и с символа @.

Ниже пример документации класса с использованием KDoc:

/**
 * A group of *members*. 
 *
 * This class has no useful logic; it's just a documentation example.
 *
 * @param T the type of a member in this group.
 * @property name the name of this group.
 * @constructor Creates an empty group.
 */
class Group<T>(val name: String) {
    /**
     * Adds a [member] to this group.
     * @return the new size of the group.
     */
    fun add(member: T): Int { ... }
}

Теги

KDoc поддерживает следующие теги:

@param <name>

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

@param name description.
@param[name] description.
@return

Описание возвращаемого функцией значения.

@constructor

Описание первичного конструктора класса.

@receiver

Описание расширения функции.

@property <name>

Описание свойства класса, имеющего указанное имя. Этот тег может использоваться для документации свойств указанных в основном кострукторе, где описание свойств прямо до их объявления выглядит нелепо.

@throws <class>, @exception <class>

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

@sample <identifier>

Добавляется в тело функции с указанным именем элемента, чтобы показать пример того, как этот элемент можно использовать.

@see <identifier>

Добавляет ссылку на спецификацию класса или метода на See Also блок документации.

@author

Определяет автора документируемого элемента.

@since

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

@suppress

Исключает элемент из генерируемой документации. Может использоваться для элементов, которые не являются частью официального API, но до сих пор должны быть доступны.

KDoc не поддерживает @deprecated тег. Вместо него используйте @Deprecated аннотацию. {:.note}

Встроенная разметка

Для встроенной разметки KDoc использует Markdown синтаксис, расширенный для поддержки сокращенного синтаксиса с возможностью привязки к другим элементам кода.

Привязка элементов

Для связи с элементом (классом, методом, свойством или параметром), достаточно указать его имя в квадратных скобках:

Use the method [foo] for this purpose.

Если вы хотите ввести свое обозначение для ссылки, используйте следующий Markdown синтаксис:

Use [this method][foo] for this purpose. 

Вы также можете использовать подходящее имя в ссылках. Заметьте, в отличие от JavaDoc, подходящее имя всегда использует точку для разделения компонентов, даже до имени метода:

Use [kotlin.reflect.KClass.properties] to enumerate the properties of the class.

На имена в ссылках действуют такие же правила, как и на имена использованные внутри документации. В частности, это означает, что если вы импортировали имя в текущий файл, вам не нужно полностью определять его, когда вы используете его в комментариях KDoc.

Заметьте, что KDoc не имеет синтаксиса для обозначения переопределенных функций. Поскольку Kotlin инструмент генерации документации добавляет все переопределенные методы в один файл, особое обозначение переопределенных функций не требуется для корректной работы ссылок.

Документирование модулей и пакетов

Документация для модуля в целом, а также пакетов в этом модуле, создается как отдельный Markdown файл, и путь до файла передается в Dokka с использованием параметра командной строки -include или соответствующих параметров в Ant, Maven и Gradle плагинах.

Внутри файла, документация для заголовка модуля и отдельных пакетов обозначается заголовком первого уровня. Текст заголовка должен содержать "Module <module name>" для модуля, и "Package <package qualified name>" для пакета.

Ниже приведены примеры документации модулей и пакетов:

# Module kotlin-demo

The module shows the Dokka syntax usage.

# Package org.jetbrains.kotlin.demo

Contains assorted useful stuff.

## Level 2 heading

Text after this heading is also part of documentation for `org.jetbrains.kotlin.demo`

# Package org.jetbrains.kotlin.demo2

Useful stuff in another package.

Есть ли у Swift поддержка генерации документации?

Комментарии к документации изначально поддерживаются в XCode, создавая грамотно оформленную документацию в быстрой справке (как в всплывающем окне при нажатии символов, так и в инспекторе быстрой справки ⌥⌘2).

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

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

Ниже приведен пример и список элементов синтаксиса, которые в настоящее время работают для комментариев документации по символам.


Xcode 7 beta 4 ~ Добавлено " - Throws: ..." как элемент списка верхнего уровня, который отображается рядом с параметрами и возвращает описания в быстрой справке.

Xcode 7 beta 1 ~ Некоторые существенные изменения в синтаксисе со Swift 2 - комментарии к документации теперь основаны на Markdown (аналогично игровым площадкам).

Xcode 6.3 (6D570) ~ Текст с отступом теперь отформатирован как блоки кода с последующими вложенными отступами. Кажется невозможным оставить пустую строку в таком блоке кода - попытка сделать это приводит к тому, что текст будет добавлен в конец последней строки с любыми символами в нем.

Xcode 6.3 beta ~ Встроенный код теперь может быть добавлен в комментарии к документации с помощью обратных галочек.


/// Text like this appears in "Description".
///
/// Leave a blank line to separate further text into paragraphs.
///
/// You can use bulleted lists (use `-`, `+` or `*`):
///
/// - Text can be _emphasised_
/// - Or **strong**
///
/// Or numbered lists:
///
/// 7. The numbers you use make no difference
/// 0. The list will still be ordered, starting from 1
/// 5. But be sensible and just use 1, 2, 3 etc…
///
/// ---
///
/// More Stuff
/// ==========
///
/// Code
/// ----
///
/// Use backticks for inline `code()`. Indentations of 4 spaces or more will create a code block, handy for example usage:
///
///     // Create an integer, and do nothing with it
///     let myInt = 42
///     doNothing(myInt)
///
///     // Also notice that code blocks scroll horizontally instead of wrapping. 
///
/// Links & Images
/// --------------
///
/// Include [links](https://en.wikipedia.org/wiki/Hyperlink), and even images:
///
/// ![Swift Logo](/Users/Stuart/Downloads/swift.png "The logo for the Swift programming language")
///
/// - note: That "Note:" is written in bold.
/// - requires: A basic understanding of Markdown.
/// - seealso: `Error`, for a description of the errors that can be thrown.
///
/// - parameters:
///   - int: A pointless `Int` parameter.
///   - bool: This `Bool` isn't used, but its default value is `false` anyway…
/// - throws: A `BadLuck` error, if you're unlucky.
/// - returns: Nothing useful.
func doNothing(int: Int, bool: Bool = false) throws -> String {
    if unlucky { throw Error.BadLuck }
    return "Totally contrived."
}


Стиль комментариев

Оба ///(встроенный) и /** */(блочный) стиль комментариев поддерживаются для создания комментариев документации. Хотя я лично предпочитаю визуальный стиль /** */комментариев, автоматическое отступление XCode может испортить форматирование для этого стиля комментариев при копировании / вставке, поскольку оно удаляет начальные пробелы. Например:

/**
See sample usage:

    let x = method(blah)
*/

При вставке отступ блока кода удаляется и больше не отображается как код:

/**
See sample usage:

let x = method(blah)
*/

По этой причине я обычно использую ///и буду использовать это для остальных примеров в этом ответе.

Блочные элементы

Заголовок:

/// # My Heading

или

/// My Heading
/// ==========


Подрубрика:

/// ## My Subheading

или

/// My Subheading
/// -------------


Горизонтальное правило:

/// ---


Неупорядоченные (маркированные) списки:

/// - An item
/// - Another item

Вы также можете использовать +или *для неупорядоченных списков, это просто должно быть последовательным.


Упорядоченные (пронумерованные) списки:

/// 1. Item 1
/// 2. Item 2
/// 3. Item 3


Блоки кода:

///    for item in array {
///        print(item)
///    }

Требуется отступ не менее четырех пробелов.

Встроенные элементы

Акцент (курсив):

/// Add like *this*, or like _this_.


Сильный (жирный):

/// You can **really** make text __strong__.

Обратите внимание, что вы не можете смешивать звездочки ( *) и подчеркивание ( _) в одном элементе.


Встроенный код:

/// Call `exampleMethod(_:)` to demonstrate inline code.


Ссылки:

/// [Link Text](https://en.wikipedia.org/wiki/Hyperlink)


Изображений:

/// ![Alt Text](http://www. example.com/alt-image.jpg)

URL-адрес может быть либо веб-URL-адресом (с использованием «http: //»), либо URL-адресом абсолютного пути к файлу (кажется, я не могу заставить работать относительные пути к файлам).

URL-адреса для ссылок и изображений также можно отделить от встроенного элемента, чтобы сохранить все URL-адреса в одном управляемом месте:

/// A [link][1] an an ![image][2]
///
/// ...
///
/// [1]: http://www.example.com
/// [2]: http://www.example.com/image.jpg

Ключевые слова

В дополнение к форматированию Markdown, XCode распознает другие ключевые слова разметки, которые отображаются на видном месте в быстрой справке. Эти ключевые слова разметки в основном принимают формат - <keyword>:(за исключением того parameter, что также включает имя параметра перед двоеточием), где само ключевое слово может быть написано с любой комбинацией символов верхнего и нижнего регистра.

Ключевые слова раздела символов

Следующие ключевые слова отображаются в виде заметных разделов в средстве просмотра справки, под разделом «Описание» и над разделом «Объявлено». Когда они включены, их порядок фиксируется, как показано ниже, даже если вы можете включить их в любом порядке, который вам нравится в ваших комментариях.

См. Полностью документированный список ключевых слов раздела и их предполагаемое использование в разделе «Команды раздела символов» справочника по форматированию разметки .

/// - parameters:
///   - <#parameter name#>:
///   - <#parameter name#>:
/// - throws:
/// - returns:

Кроме того, вы можете написать каждый параметр следующим образом:

/// - parameter <#parameter name#>:

Символ Описание Ключевые слова поля

Следующий список ключевых слов отображается в виде жирных заголовков в теле раздела «Описание» средства просмотра справки. Они будут отображаться в любом порядке, в котором вы их пишете, как и в остальной части раздела «Описание».

Полный список перефразирован из этой замечательной статьи Эрики Садун. Также см. Полностью документированный список ключевых слов и их предполагаемое использование в разделе «Команды поля описания символа» в справочнике по форматированию разметки .

атрибуции:

/// - author:
/// - authors:
/// - copyright:
/// - date:

Доступность:

/// - since:
/// - version:

Наставления:

/// - attention:
/// - important:
/// - note:
/// - remark:
/// - warning:

Состояние развития:

/// - bug:
/// - todo:
/// - experiment:

Качество реализации:

/// - complexity:

Функциональная семантика:

/// - precondition:
/// - postcondition:
/// - requires:
/// - invariant:

Перекрестная ссылка:

/// - seealso:

HTML-документация (предназначенная для имитации собственной документации Apple) может быть сгенерирована из встроенной документации с использованием утилиты командной строки с открытым исходным кодом Jazzy .

$ [sudo] gem install jazzy
$ jazzy
Running xcodebuild
Parsing ...
building site
jam out ♪♫ to your fresh new docs in `docs`

Пример консоли, взятый из этой статьи NSHipster

Документирование исходного кода в java — Информатика, информационные технологии

Одной из важнейших частей написания программного обеспечения является документирование создаваемого кода. В Java для этих целей применяется средство, обеспечивающее поддержку на уровне синтаксиса языка программирования – специализированные комментарии. Они начинаются с комбинации символов /** и заканчиваются комбинацией символов */

Часть комментариев автоматически создаёт среда разработки.

Пример:

/**

* Creates new form GUI_application

*/

Средством обработки внедрённых в исходный код комментариев и создания для класса справочных HTML-файлов является инструмент javadoc, входящий в состав JDK. Но в среде NetBeans удобнее пользоваться вызовом через главное меню: Build/Generate Javadoc for “…”.

Документационные комментарии бывают для:

  • Пакетов (пока не функционируют).
  • Классов.
  • Интерфейсов.
  • Пользовательских типов-перечислений (на уровне пакетов пока не функционируют, но можно использовать для типов, заданных в классах).
  • Методов.
  • Переменных.

Документационные комментарии пишутся непосредственно перед заданием соответствующей конструкции – пакета, класса, интерфейса, типа-перечисления, метода или переменной. Следует учитывать, что по умолчанию документация создаётся только для элементов, имеющих уровень видимости public или protected.

Пример фрагмента кода с документационными комментариями:

/**

* Пример приложения Java с документационными комментариями

* В приложении заданы типы-перечисления Monthes и Spring и показано,

* как с ними работать.

* Кроме того, дан пример использования класса из другого пакета.

* @see enumApplication.Monthes Информация о типе-перечислении Monthes

* @see enumApplication. Spring

* @see enumApplication#m1

* @version Версия 0.1 Первоначальная версия, проверено при компиляции

* в среде NetBeans 5.5

* @author Вадим Монахов

*/

public class enumApplication extends javax.swing.JFrame {

int i=1;

/**

* Spring — задаёт перечисление из 3 весенних месяцев года: march,apr,may.

*

*

  • march
  • *

  • apr
  • *

  • may
  • *

    * Идентификатор для марта записан отличающимся от соответствующего

    * идентификатора в перечислении Monthes, а для апреля и мая записаны так

    * же — чтобы подчеркнуть, что их пространства имён независимы.

    */

    public enum Spring {march,apr,may};

    /**

    * Monthes — задаёт перечисление из 12 месяцев года:

    * jan,feb,mar,apr,may,jun,jul,aug,sep,oct,nov,dec

    * (январь, февраль и т.д.)

    */

    public enum Monthes {jan,feb,mar,apr,may,jun,jul,aug,sep,oct,nov,dec};

    Spring spr1= Spring. apr, spr2;

    /**

    *Переменная, иллюстрирующая работу с перечислениями

    */

    public Monthes m1,m2=Monthes.mar,m3;

    Имеется два типа кода внутри блока документационного комментария – HTML-текст и метаданные (команды документации, начинающиеся с символа @ ). Если пишется обычный текст, он рассматривается как HTML-текст, поэтому все пробелы и переносы на новую строку при показе приводятся к одному пробелу. Для того, чтобы очередное предложение при показе начиналось с новой строки, следует вставить последовательность символов
    , называющуюся тегом HTML. Возможно использование произвольных тегов HTML, а не только тега переноса на новую строку: теги неупорядоченного списка

      и
    • , теги гиперссылок, изображений и т.д. В то же время не рекомендуется использовать заголовки и фреймы, поскольку это может привести к проблемам – javadoc создаёт на основе документационного кода собственную систему заголовков и фреймов. Кроме того, при преобразовании в HTML-документ из документационного кода удаляются символы “*”, если они стоят на первом значимом месте в строке (символы пробелов не являются значимыми).

    Для более подробного изучения тегов HTML следует читать справочную или учебную литературу по этому языку разметки документов. Соответствующие ссылки и документы можно найти, например, на сайте автора

    http://barsic.spbu.ru/ www/comlan/html_r.html

    Команды документации (символы метаданных):

    • @see (“смотри”) – применяется для создания в документе гиперссылок на другие комментарии. Можно использовать для любых конструкций (классов, методов и т.д. ). Формат использования: @see ИмяКласса – для класса; @see ИмяКласса.ИмяПеречисления – для типа-перечисления, заданного в классе; @see ИмяКласса#ИмяЧлена – для метода или переменной; для интерфейса – аналогично классу. При этом имя класса или интерфейса может быть либо коротким, либо квалифицировано именем пакета.
    • @version (“версия”) – информация о версии. Используется для классов и интерфейсов. Формат использования: @version Информация о версии в произвольной форме.
    • @author (“автор”) — Информация об авторе. Используется для классов и интерфейсов. Формат использования: @author Информация об авторе в произвольной форме. Может включать не только имя, но и данные об авторских правах, а также об электронной почте автора, его сайте и т.д.
    • @since (“начиная с”) — Информация о версии JDK, начиная с которой введён или работоспособен класс или интерфейс. Формат использования: @since Информация в произвольной форме.
    • @param (сокращение от parameter -“параметр”) — информация о параметре метода. Комментарий /** @param … */ ставится в месте декларации метода в списке параметров перед соответствующим параметром. Формат использования: @param ИмяПараметра Описание.
    • @return (“возвращает”) — информация о возвращаемом методом значении и его типе. Формат использования: @return Информация в произвольной форме.
    • @throws (“возбуждает исключение”) — информация об исключительных ситуациях, которые могут возбуждаться методом. Формат использования: @throws ИмяКлассаИсключения Описание.
    • @deprecated (“устаревшее”) — информация о том, что данный метод устарел и в последующих версиях будет ликвидирован. При попытке использования таких методов компилятор выдаёт программисту предупреждение (warning) о том, что метод устарел, хотя и компилирует проект. Формат использования: @deprecated Информация в произвольной форме.

    Признаком окончания команды документации является начало новой команды или окончание комментария.

    Пример документации, созданной для пакета, из которого взят приведённый выше фрагмент кода:

    Головная страница файлов документации

    Страница описания элементов пакета java_enum_pkg

    Страница описания класса enumApplication

    Обратите внимание, что в краткой сводке (summary) приводятся только начальные строки соответствующей информации по элементам пакета или класса. Полную информацию можно прочитать после перехода по гиперссылке в описании соответствующего элемента. Поэтому важно, чтобы первые 2-3 строки информации содержали самые важные сведения.

    Статьи к прочтению:

    Java. Спецвыпуск 2. Генератор документации Javadoc


    Похожие статьи:

    Восемь причин использовать PHPDoc

    Часто встречаю вопрос о том, что же это за странные блоки комментариев постоянно генерируются в представлениях:

    <?php
    <?php
     @var 
     @var 
     @var 
    ?>

    в ActiveRecord-классах:

     @property  @property  @property  @property  @property 
    class User extends ActiveRecord
    {
        ...
    }

    и перед всеми методами:

     @param  @param  @return 
    public function save($runValidation = true, $attributeNames = null)
    {
        ...
    }

    Что они обозначают и зачем они нужны? Это какой-то особый синтаксис объявления переменных в PHP или что?

    Нет, это не совсем синтаксис PHP. А точнее, к самому PHP он никакого отношения не имеет и сам PHP интерпретатор его никогда не парсит. Это PHPDoc-блок, зародившийся ещё как JavaDoc и перешедший в PHPDocumentor

    Пока мы не кодим так, как зажигают эти чуваки:

    но попробуем разобраться.

    Все эти вещи, судя по названию, как-то связаны с документацией. С неё и начнём.

    Документация кода

    Кому то стало лень писать документацию отдельно и он, вероятно, решил: «Отдельно документировать проект сложно и муторно. Нам же проще описывать прямо в комментариях каждый метод и класс. Давайте сделаем особый вид комментариев и при необходимости будем генерировать документацию по нему». И понеслось. В итоге придумали конструкции для объявления переменных, их типов и прочей метаинформации. И написали автоматический генератор, который парсит файлы в папке и генерирует HTML-файлы для каждого нашего класса.

    Если посмотреть в API Reference и в код класса то увидим одно и то же:

    namespace yii\db;
     
    
    class ActiveRecord extends BaseActiveRecord
    {
        ...
    }

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

    Так что можем уже сформулировать первый бонус, который нам дают PHPDoc-блоки:

    Применение первое: Возможность одной командой в консоли сгенерировать документацию с описанием всех классов, полей и методов своего проекта.

    Но кроме этого чем он полезен в реальной жизни? Рассмотрим ещё несколько применений.

    Виртуальные поля

    В модели данных он пригодится для той же автогенерации полей по классу, но для чего его используют в представлениях, которые в документации не выводятся?

    Оказалось, что формат PHPDoc оказался настолько удачным, что его встроенную поддержку наряду с JavaDoc подхватили практически все IDE вроде PhpStorm, NetBeans и прочие. В PHP нет встроенной типизации для чисел и строк, поэтому указывать тип в комментарии (чтобы не забыть) было бы полезно. Вот и нашему PHP-редактору оттуда тоже оказалось удобно парсить переменные и их типы.

    Например, был класс без полей:

    class Post extends ActiveRecord
    {
        public static function tableName() {
            return '{{%post}}';
        }
    }

    и непонятно что там, так как Yii2 берёт атрибуты из таблицы в базе данных. Автоподстановка видит только поля и методы из базового класса ActiveRecord:

    А наши поля подчёркивает, при этом ругаясь, что их в объекте нет:

    Можно заморочиться и написать плагин, который бы парсил поля из базы для каждой таблицы. Но это явно не лёгкий путь.

    А давайте просто обозначим поля в PHPDoc-блоке (комментарии особой формы):

     @property  @property  @property  @property  @property  @property  @property  @property 
    class Post extends ActiveRecord
    {
        public static function tableName() {
            return '{{%post}}';
        }
    }

    и редактору сразу станет понятно, какие поля теперь там есть для автоподстановки и какого они типа:

    Теперь он в курсе наших дел и больше не ругается.

    Или если в классе есть связи:

     @property  @property  @property  @property  @property 
    class Post extends ActiveRecord
    {
        public function getCategory()
        {
            return $this->hasOne(Category::className(), ['id' => 'category_id']);
        }
     
        public function getUser()
        {
            return $this->hasOne(Category::className(), ['id' => 'category_id']);
        }
     
        public function getTags()
        {
            return $this->hasMany(Tag::className(), ['id' => 'tag_id'])->viaTable(PostTag::tableName(), ['post_id' => 'id']);
        }
    }

    В коде мы можем использовать их просто как поля category, user и tags:

    echo $post->category->name;
     
    echo $post->user->username;
     
    foreach ($post->tags as $tag) {
        echo $tag->name;
    }

    Но этих полей в классе нет. Всё работает через виртуальные методы и геттеры. Поэтому нам ничего не остаётся, как указать эти псевдополя и их типы явно:

     @property  @property  @property  @property  @property  @property  @property  @property 
    class Post extends ActiveRecord
    {
        . ..
    }

    Так что PHPDoc-блок перед классом может содержать полное перечисление того, чего в классе нет.

    Применение второе: Указание псевдополей класса.

    В примерах мы рассмотрели пока только поля. К псевдометодам подойдём позже.

    Типы существующих полей

    Помимо блока перед классом можно использовать и другие места.

    Допустим, что у нас есть приватное поле _user у класса PasswordChangeForm:

    class PasswordChangeForm extends Model
    {
        ...
     
        private $_user;
     
        public function __construct($user, $config = [])
        {
            $this->_user = $user;
            parent::__construct($config);
        }
     
        ...
     
        public function changePassword()
        {
            if ($this->validate()) {
                $user = $this->_user;
                $user->setPassword($this->newPassword);
                return $user->save();
            } else {
                return false;
            }
        }
    }

    Но на строках:

    $user = $this->_user;
    $user->setPassword($this->newPassword);
    return $user->save();

    редактор впадает в ступор и методы setPassword и save подсвечивает жёлтым, мотивируя это тем, что таких методов в этой переменной нет:

    А если мы подскажем, что там у нас находится объект класса User:

    class PasswordChangeForm extends Model
    {
         @var 
        private $_user;
    }

    то всё заработает как нам этого и хотелось.

    Здесь мы аннотации @var передаём только тип. Но вообще ей можно передавать имя переменной, её тип или оба аргумента сразу.

    Применение третье: Подсказка типов для имеющихся полей в классе.

    Тип возвращаемого результата

    Аналогично, если мы аннотацией @return укажем тип возвращаемого методом объекта:

    class UsersController extends Controller
    {
         @param  @return  @throws 
        protected function findModel($id)
        {
            if (($model = User::findOne($id)) !== null) {
                return $model;
            } else {
                throw new NotFoundHttpException('The requested page does not exist.');
            }
        }
    }

    то при использовании этого метода наша система разработки поймёт, что внутри переменной $user после вызова данного метода окажется объект класса User:

    class UsersController extends Controller
    {
        public function actionUpdate($id)
        {
            $model = $this->findModel($id);
     
            if ($model->load(Yii::$app->request->post()) && $model->save()) {
                return $this->redirect(['view', 'id' => $model->id]);
            } else {
                return $this->render('update', [
                    'model' => $model,
                ]);
            }
        }
    }

    и больше не будет ругаться на ранее неизвестные ей методы load и save.

    А что если какой-либо метод возвращает нам либо User, либо null? Тогда можно перечислить варианты через вертикальную черту:

    /**
     * @param integer $id
     * @return User|null
     */
    

    И IDE будет учитывать оба случая.

    Применение четвёртое: Подсказка типов аргументов и типа возвращаемого результата (при наличии) у процедур, функций, методов.

    Переменные из ниоткуда

    Или ещё вариант. Есть некое представление, в которое из контроллера передаётся переменная $model. К тому же, это представление рендерится в объекте класса \yii\web\View, который и будет доступен через $this:

    <?php
    <?php
    use yii\helpers\Html;
    use yii\widgets\DetailView;
     
    $this->title = $model->meta_title;
    $this->registerMetaTag(['name' => 'description', 'content' => $model->meta_description]);
    $this->registerMetaTag(['name' => 'keywords', 'content' => $model->meta_keywords]);
     
    $this->params['breadcrumbs'][] = ['label' => 'Блог', 'url' => ['index']];
    $this->params['breadcrumbs'][] = $this->title;
    ?>
    <div>
     
        <h2><?= Html::encode($this->title) ?></h2>
     
        . ..
     
    </div>

    Но IDE не в курсе наших планов, поэтому сразу подсвечивает переменные $this и $model как не определённые в этом файле. Для исправления ситуации мы можем добавить сколько угодно Doc-блоков с аннотацией @var прямо внутрь кода представления:

    <?php
    <?php
    use yii\helpers\Html;
    use yii\widgets\DetailView;
     
     @var 
     @var 
     
    $this->title = $model->meta_title;
    ...
    ?>

    При этом для @var можно указать сначала тип, потом имя переменной:

    В итоге автоподстановка, поиск и автозамена полей и методов объектов заработают для этих переменных автоматически.

    Применение пятое: Обозначение переменных, каким-либо образом переданных извне.

    Подмена типа

    Не всегда мы в контроллерах и прочих компонентах используем метод findModel. Часто можно напрямую в коде выполнить какой-нибудь запрос:

    $model = Post::find()->where(['id' => $id])->andWhere(. ..)->one();
     
    echo $model->title;

    В итоге IDE по цепочке наследования подсмотрит аннотации метода ActiveRecord::find:

    class ActiveRecord extends BaseActiveRecord
    {
         @inheritdoc
     @return 
        public static function find()
        {
            return Yii::createObject(ActiveQuery::className(), [get_called_class()]);
        }

    и, так как указана аннотация @inheritdoc, пойдёт ещё выше в аннотации этого же метода в интерфейсе:

    interface ActiveRecordInterface
    {
         @return 
        public static function find();
    }

    и склеит всё воедино.

    В итоге IDE по строке:

    поймёт, что из метода find должен вернуться экземпляр класса \yii\db\ActiveQuery и методы where и one будут вызываться уже у него:

    class ActiveQuery extends Query implements ActiveQueryInterface
    {
        ...
     
         @param  @return 
        public function one($db = null)
        {
            ...
        }
    }

    и здесь мы видим, что метод one возвращает либо экземпляр ActiveRecord, либо массив (если вызывали asArray()), либо null. Редактор так и будет думать, поэтому выдаст замечание при попытке обратиться к полю title:

    $model = Post::find()->where(['id' => $id])->one();
     
    echo $model->title;

    Для правильной работы нам нужно явно указать тип переменной с помощью Doc-блока перед присваиванием:

     @var 
    $model = Post::find()->where(['id' => $id])->one();
     
    echo $model->title;

    или непосредственно перед использованием объекта:

    $model = Post::find()->where(['id' => $id])->one();
     
     @var 
    echo $model->title;

    Это удобно делать в циклах по различным выборкам:

    foreach (Category::find()->orderBy('name')->each() as $category) {
         @var 
        echo $category->title;
    }

    Применение шестое: Подмена типа уже существующих переменных.

    И вернёмся к методам.

    Подключение примесей

    Вначале мы рассмотрели виртуальные переменные. Теперь предположим, что к своему классу мы примешиваем любое поведение вроде:

    composer require yii-dream-team/yii2-upload-behavior
    

    Его достаточно добавить в метод behaviors:

     @property  @property  @property  @property  @property  @property 
    class Post extends ActiveRecord
    {
        . ..
     
        public function behaviors()
        {
            return [
                [
                    'class' => ImageUploadBehavior::className(),
                    'createThumbsOnRequest' => true,
                    'attribute' => 'image',
                    'filePath' => '@webroot/uploads/posts/[[pk]].[[extension]]',
                    'fileUrl' => '@web/uploads/posts/[[pk]].[[extension]]',
                    'thumbPath' => '@webroot/uploads/posts/[[profile]]_[[pk]].[[extension]]',
                    'thumbUrl' => '@web/uploads/posts/[[profile]]_[[pk]].[[extension]]',
                    'thumbs' => [
                        'thumb' => ['width' => 100, 'height' => 100],
                        'preview' => ['width' => 250, 'height' => 180],
                    ],
                ],
            ];
        }
    }

    и в представлениях выводить оригинал или превью:

    <?php
    <?= Html::img($post->getImageFileUrl('image')) ?>
    <?= Html::img($post->getThumbFileUrl('image', 'preview')) ?>

    А мы помним, что IDE ругается на всё, чего нет в классе. Но с помощью аннотации @mixin, которую поддерживает IDE PhpStorm и, возможно, некоторые другие, можно «подмешать» класс поведения:

     @property  @property  @property  @property  @property  @property  @mixin 
    class Post extends ActiveRecord
    {
        ...
    }

    и все методы getImageFileUrl и прочие будут доступны в автоподстановке.

    Но есть один нюанс. Помимо нужных методов в классе поведения имеется и много ненужных. Например, вспомогательные resolveProfilePath или createThumbs, которые мы использовать не будем.

    В таком случае вместо примешавания всего класса поведения с помощью @mixin мы можем просто добавить определение только пары нужных нам виртуальных методов:

     @property  @property  @property  @property  @property  @property  @method  @method 
    class Post extends ActiveRecord
    {
        ...
    }

    Аналогично можно добавлять сигнатуры любых своих методов, работающих через свой магический метод __call.

    Применение седьмое: Определение псевдометодов класса.

    Программирование с аннотациями

    Помимо простой работы с PHPDocumentor некоторые системы пошли дальше и придумали для своих целей собственные виды аннотаций. И некий программный код через рефлексию парсит эти данные. Взять хоть первый попавшийся пример с сайта StackOverflow:

    $r = new ReflectionClass($class);
    $doc = $r->getDocComment();
    preg_match_all('#@(.*?)\n#s', $doc, $annotations);
    print_r($annotations[1]);

    Аналогично можно получить $r->getMethods() и парсить уже их.

    В итоге этот подход нашёл новое применение. Например, в Symfony Framework с помощью собственных аннотаций (помимо конфигурации в YAML или XML-файлах) с использованием пакета doctrine/annotations можно конфигурировать те же сущности прямо в коде:

    namespace AppBundle\Entity;
     
    use Doctrine\ORM\Mapping as ORM;
     
    
    class Product
    {
        
        protected $id;
     
        
        protected $name;
     
        
        protected $price;
     
        
        protected $description;
    }

    или ту же маршрутизацию контроллеров:

    class BlogController extends Controller
    {
        
        public function showAction($slug)
        {
            
        }
    }

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

    Также в уроке по тестированию мы рассматривали аннотации вроде @group и @dataProvider для тестов в пакете PHPUnit.

    Этот подход уже мало связан с оригинальным PHPDoc, так как просто использует его идею. Но при этом друг другу никто не мешает и можно спокойно использовать различные ключи вместе:

    class Product
    {
         @var 
        protected $name;
    }

    Многим такой подход с конфигурированием аннотациями в Symfony не нравится, так как он нарушает принцип единой ответственности, смешивая программный код и конфигурацию в одном файле. Так что используйте по своему усмотрению.

    Восьмая причина: Появление программных систем с поддержкой специфических аннотаций.

    Пока на этом всё. Если в комментариях приведут и другие примеры использования, то дополню статью.

    И в итоге

    С помощью PHPDoc-блоков можно легко «научить» свой редактор понимать вас с полуслова и всегда знать, какие переменные и каких типов используются в каждой строчке кода.

    После этого не будет проблем с автоподстановкой, опечатками, несовпадениями типа, неопределёнными переменными, с автоматическим переименованием полей или методов любого класса и прочим автоматическим рефакторингом.

    Дружите со своей IDE и она облегчит вашу жизнь.

    Ну и, вроде, праздник скоро, так что не спалите ёлку:

    25 причин нашей любви к Java

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

    [Оригинал] Original post in English is written by Trisha Gee

    В JetBrains мы любим разные языки программирования. Но сегодня хочется уделить особое внимание Java, ведь ей в этом месяце исполняется 25 лет! Вот 25 причин нашей любви к Java и JVM.

    Обратная совместимость

    Java — едва ли не единственный язык, на свежих версиях которого можно запускать код, написанный 25 лет назад. Разработчики языка очень серьезно относятся к обратной совместимости, поэтому многие организации выбирают Java в качестве основной технологии, зная, что старый код будет запускаться на JVM еще долгие годы.

    Зрелость

    Многие из достоинств Java напрямую связаны с тем, как долго она существует. За прошедшие 25 лет приложения на Java разрабатывались под разные платформы в самых разных сферах. Кроме того, все эти годы люди изучали Java в школах, университетах, на курсах по программированию и в процессе работы. Естественно, вокруг языка сформировалась большая экосистема, которая продолжает расти и развиваться, накапливая опыт и знания. Сам язык и решения, которые он предлагает, хорошо документированы и поддерживаются вендорами и некоммерческими организациями, а также отдельными пользователями. А еще широкое применение языка означает, что для Java-разработчиков есть много рабочих мест.

    Постоянное развитие

    В случае Java зрелость и обратная совместимость не противоречат активному развитию платформы и языка. С 2017 года, начиная с Java 9, новые версии языка выпускаются раз в полгода: Java постоянно меняется и улучшается. Благодаря preview-функциональности разработчики языка могут экспериментировать с новым синтаксисом, собирать отзывы сообщества, а затем стандартизировать функции, которые действительно полезны тем, кто пишет на Java.

    Равновесие

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

    Для тех, кому важна стабильность, выпускаются версии с долгосрочной поддержкой. Чтобы уменьшить риски во время обновления, такие пользователи могут периодически тестировать версии, выходящие каждые полгода. А те, кто предпочитает регулярно обновляться, могут переходить на свежую версию Java каждые шесть месяцев. Разработчики, которые хотят попробовать новый синтаксис до его стандартизации, могут включить preview-функциональность или воспользоваться ранним доступом к версии, которая еще не вышла. Команды, выбирающие свежие версии Java, действительно получают все самое лучшее.

    Стандарты

    Стандарты, может быть, не так интересны разработчикам, как языковые возможности, но наличие стандартов для Java, Java EE, Jakarta EE и для распространенных сценариев использования действительно упрощает жизнь. Благодаря стандарту JDBC для взаимодействия с базами данных, не нужно беспокоиться о том, как реализован драйвер базы данных: мы взаимодействуем с ней всегда одинаково. Java Community Process — один из процессов стандартизации Java.

    Спецификация языка Java описывает, что за язык представляет из себя Java и как должен работать компилятор. К ней относится и модель памяти Java, которая помогает разработчикам сделать выводы о поведении программы независимо от JVM или оборудования. Спецификация Java Virtual Machine описывает низкоуровневое устройство JVM. Благодаря этим спецификациям разные JDK, распространяемые разными поставщиками и работающие на разных платформах, ведут себя предсказуемым образом. Что приводит нас к…

    Write Once Run Anywhere

    Принцип WORA («Напиши один раз — запускай где угодно») в наши дни кажется настолько очевидным, что трудно представить, насколько революционной эта идея была для своего времени. Мне довелось поработать в одной очень большой организации, которая еще в 2002 году перешла с предыдущего стека на Java просто потому, что у них стояло без дела много разного оборудования, на котором можно было запускать новые Java-приложения, вместо того чтобы покупать специальное железо. Это была одна из главных причин, по которой они перевели все свои разработки на Java. В эпоху облачных технологий все это может показаться менее актуальным, но то, что мы не всегда видим принцип WORA в действии, не означает, что мы не используем его. И конечно же, если вы работаете в IntelliJ IDEA (или NetBeans), вы пользуетесь преимуществами WORA на своем компьютере.

    Производительность

    Тех, кто не так хорошо знаком с Java, иногда удивляет, что это очень высокопроизводительный язык. Не стоит забывать, что перед нами зрелая платформа и ее производительность улучшалась на протяжении 25 лет: доступны многочисленные сборщики мусора с различными профилями производительности, да и JVM оптимизирует код во время выполнения для разных сценариев использования гораздо лучше, чем большинство разработчиков. Например, Java широко используется в финансовой сфере, в которой многое зависит от скорости транзакций и предсказуемой производительности.

    Сборка мусора

    Спустя 25 лет мы воспринимаем автоматическую сборку мусора как что-то само собой разумеющееся. Не нужно думать, как распределяется память в приложении и как ее освободить. У каждой JVM есть один или несколько алгоритмов очистки памяти: можно выбрать тот, который лучше подходит для нашего приложения, и приступать к написанию бизнес-логики, не задумываясь о том, что происходит внутри.

    Контроль и управление

    Если мы хотим знать, что происходит во время работы приложения, у нас есть большой выбор инструментов. Многие из них бесплатны, а Java Flight Recorder и Mission Control теперь входят в OpenJDK (начиная с Java 11). Такие инструменты, как JMX, даже позволяют динамически управлять приложениями.

    Java Virtual Machine (JVM)

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

    Другие языки JVM

    Причина, по которой Java не просто выжила, а продолжала развиваться в период затишья между выходом Java 6 и 8 (в Java 7 есть интересные возможности, но Java-разработчики не восприняли ее как большой релиз) связана с другими языками JVM. Наш любимый, конечно же, Kotlin, но помимо него, для JVM разрабатываются и популярные Groovy, Scala, Clojure, JRuby, и новые языки, и реализации существующих языков. Совместимость между языками JVM и классической Java помогает нам извлекать пользу из этого разнообразия.

    Библиотеки и фреймворки

    Один из наиболее убедительных аргументов в пользу Java — огромный выбор библиотек и фреймворков, многие из которых с открытым исходным кодом и распространяются бесплатно. Такие популярные фреймворки, как Spring и Spring Boot, значительно упрощают разработку как небольших сервисов, так и сложных корпоративных приложений. Благодаря стандартам нетрудно разобраться в любой библиотеке: вы наверняка уже использовали нечто подобное в другом контексте. Поскольку в сообществе с ранних времен распространен открытый исходный код, для стандартных проблем обычно уже есть решение и не нужно изобретать велосипед. Кроме того, так как многие из этих решений существуют давно и широко используются, они тщательно протестированы, поняты и хорошо задокументированы.

    Инструменты сборки и управление зависимостями

    Давно прошли те времена, когда бедным разработчикам (и мне!) приходилось искать в интернете неизвестный JAR-файл, содержащий определенный класс, по-видимому, необходимый для запуска программы. В частности, Maven и Gradle упростили не только сборку и развертывание приложений, но и стандартную настройку проекта со всеми необходимыми зависимостями. Сейчас легко начать писать код как в новом, так и в существующем проекте. Общедоступные репозитории, например Maven Central и Bintray, упрощают поиск и публикацию библиотек.

    JUnit и автоматизированное тестирование

    JUnit появилась в 1997 году — почти так же давно, как и сама Java! На сегодняшний день это самая популярная платформа автоматизированного тестирования в мире Java. Как JUnit, так и TestNG поставляются вместе с IntelliJ IDEA: предполагается, что для любого нового Java-проекта необходим фреймворк тестирования. Вполне вероятно, что современные тестовые фреймворки для самых разных языков основаны на идеях, впервые реализованных в JUnit. Культура автоматизированного тестирования, принятая в Java-сообществе, во многом обязана именно этой библиотеке.

    IDE

    В своем блоге мы не можем не упомянуть IntelliJ IDEA. Не важно, считаете ли вы, что IDE вам необходима из-за многословности Java или что статическая типизация Java позволяет использовать всю мощь IDE, факт остается фактом: Java-разработчики любят IDE (а мы любим вас!). Если научиться эффективно пользоваться IDE, будь то IntelliJ IDEA, Eclipse или NetBeans, можно программировать значительно продуктивнее с помощью автодополнения и генерации кода, функциональности запуска тестов, отладки, навигации и многих других возможностей. Большинство Java-разработчиков очень ценят преимущества, которые им дают IDE.

    Сообщество

    Java-комьюнити — это большое, активное и гостеприимное сообщество единомышленников. Свои Java-сообщества есть во многих городах мира, а те, у кого нет возможности попасть на митап, могут присоединиться к Virtual Java User Group. Java Champions, технические эксперты из мира Java, делятся знаниями и опытом с разработчиками, пишущими на Java и языках JVM. На Java написано огромное количество проектов с открытым исходным кодом, включая сам JDK (OpenJDK). В Java-сообществе ценят обучение и развитие навыков, следуют стандартам и лучшим практикам, стараясь прагматично оценивать их применимость в реальных условиях.

    Люди

    Любое сообщество — это в первую очередь люди. Когда я спрашивала у разработчиков, что они больше всего ценят в языке, многие из них называли именно людей из Java-мира, которые оказали на них влияние. Одни называли своих коллег и учителей, другие — таких людей, как Брайан Гетц, Энджи Джонс, Жорж Сааб, Мала Гупта, Венкат Субраманиам. Кто-то даже назвал меня. Сама я пришла в мир Java, потому что изучала этот язык в университете и с ним было легко найти работу, а осталась, потому что здесь замечательные люди, от которых я получила много помощи и поддержки.

    Javadoc и документация

    Благодаря Javadoc документация API становится важной частью языка. Три типа комментариев (Javadoc, строчные и блочные) четко показывают, какое именно пояснение добавляет разработчик. Javadoc служат специально для того, чтобы оставлять полезную документацию для других разработчиков, которые вызывают определенный метод, используют класс или пакет. Если разработчик не может найти нужную информацию о библиотеке или фрагменте кода, обычно есть Javadoc, который подскажет правильное направление поиска.

    Кроме того, в экосистеме Java, как правило, ожидают получить (и предоставляют другим) документацию хорошего качества. Потенциальных контрибьюторов проектов с открытым исходным кодом призывают отправлять пулреквесты, содержащие комментарии Javadoc и другую документацию. Разработчики со всего мира отвечают на вопросы друг друга на StackOverflow и пишут в блогах о решении конкретных проблем.

    Открытый исходный код

    Java-сообщество довольно рано начало придерживаться принципов открытого исходного кода, а теперь благодаря OpenJDK и сам JDK стал открытым. Это облегчает сотрудничество различных вендоров, а также отдельных разработчиков. И конечно, интересно посмотреть на код самой Java. Открытый исходный код — это отличная возможность учиться у людей, которые уже проделали большую работу и нашли решения для сложных проблем.

    Бесплатные инструменты

    Платформа Java и многие популярные инструменты, используемые в экосистеме, бесплатны для разработчиков, а часто и для коммерческих организаций. Даже после того как Oracle изменила модель лицензирования с выходом Java 11, она (и многие другие поставщики) по-прежнему предоставляет возможность пользоваться языком бесплатно. Уже упомянутые проекты с открытым исходным кодом, IDE и инструменты сборки либо бесплатны, либо имеют бесплатную версию. Это делает Java привлекательной для начинающих разработчиков и компаний с ограниченным бюджетом.

    ООП

    Объектно-ориентированное программирование, конечно, не единственная парадигма, и у всех есть свои преимущества и недостатки. Java с самого начала была спроектирована как объектно-ориентированный язык, и в ней реализованы многие шаблоны и лучшие практики ООП. Если вы выбираете объектно-ориентированный язык программирования, Java должна быть на первом месте в вашем списке.

    Развитие и адаптация

    Java была и остается объектно-ориентированным языком. При этом она позаимствовала некоторые концепции из функционального программирования (например, лямбда-выражения и неизменяемые структуры данных), которые были успешно адаптированы к ООП. Вывод типов (например, var) позволяет пользоваться преимуществами статически типизированного языка с меньшим количеством стереотипного кода. Информатика все еще относительно молодая дисциплина, и, получая новые знания, мы можем совершенствовать существующие инструменты. И сам язык, и экосистема Java постоянно развиваются в соответствии с новыми тенденциями и практиками, отражают изменения, происходящие в мире.

    Java может заимствовать идеи и синтаксис из других языков JVM и тестировать, что сработает, а что, возможно, не впишется в классический Java-мир. Даже процессы и инструменты, которые Java использует для своего развития, такие как JCP и OpenJDK, постоянно адаптируются к стремительным изменениями в индустрии. Развитие и адаптация — основы того равновесия, которое Java стремится удержать.

    Акцент на удобочитаемости

    Обычно Java-код могут читать даже те, кто не пишет на Java. Язык нельзя назвать лаконичным, он скорее многословный, и это облегчает понимание при чтении. Разработчики языка не стали включать в Java такие функции, как перегрузка операторов: важно, чтобы программистов не удивляли неожиданные изменения в поведении программы. Java стремится избегать «магии» в языке и во фреймворках. И хотя некоторые фреймворки все же построены на принципе Convention over configuration при котором многое не зависит от действий разработчика, определенно был сделан шаг от АОП с использованием аннотаций в направлении использования аннотаций для проверок документации и статического анализа. Традиционно в Java-сообществе любят следовать стандартам и лучшим практикам, поэтому Java-код часто соответствует одним и тем же правилам даже в очень разных проектах.

    Возможности языка

    Мы уже назвали 23 причины, почему любим Java, но до сих пор не упомянули ни одной языковой функции! Честно говоря, было бы очень трудно отобрать всего лишь 25 возможностей языка. К тому же, мы любим Java не только за синтаксис и функциональность. Вот одни из лучших функций Java, по мнению разработчиков:

    • Collections API: давно с нами и все также полезен.
    • Компактные фабричные методы для коллекций: значительно упрощают создание неизменяемых коллекций.
    • Streams API: отличное дополнение к Сollections API, которое здорово изменилось со времен Java 8. Параллельные потоки — новый способ использования современных устройств.
    • Лямбда-выражения: особенно полезны в сочетании со Streams API, но хороши и сами по себе.
    • Optional: хороший способ выразить, что метод может вам нечего не возвращать (и помогает забыть о NullPointerException!). Со времен Java 8 класс Optional значительно улучшился.
    • java.time: новый API для работы с датами и временем, очень полезное улучшение.
    • Checked-исключения: люди спорят, что лучше, checked или runtime-исключения. Хорошо, что checked-исключения в принципе есть.
    • Аннотации: аннотации похожи на документацию для компилятора и дают необходимую информацию фреймворкам для решения сложных задач.
    • JShell: теперь у Java есть своя интерактивная консоль REPL
    • var: вывод типов помогает уменьшить шум в коде, если используется разумно.
    • Модификаторы доступа и модульность: Java (особенно, начиная с Java 9) позволяет легко задавать уровни доступа для полей, методов, классов и модулей.
    • Switch-выражения: теперь если используется switch, код выглядит гораздо симпатичнее!
    • Информативные NullPointerExceptions: кто не любит NullPointerException? Сообщение об ошибке стало более информативным, и мы видим, где именно в цепочке вызовов возникло исключение.
    • Preview-функциональность: мы обожаем экспериментальную функциональность! Нам очень нравятся Records, сопоставление с образцом для instanceof и текстовые блоки.

    Перспективы

    Новая функциональность появляется раз в полгода, а каждый LTS-релиз обычно улучшает производительность ваших приложений. Java 15 ожидается в сентябре 2020 года и будет включать в себя hidden-классы, текстовые блоки (уже не как preview), обновленные Records и сопоставление с образцом для instanceof, а также sealed-классы (preview).

    Что мы надеемся увидеть в будущем: Project Loom обещает нам легковесный и простой в использовании параллелизм, нас ждут встроенные типы из Project Valhalla и больше языковых изменений из Project Amber, например Lambda Leftovers. Project Panama облегчит доступ к внешним API, а Project Leydon сократит время запуска, будут улучшения в различных сборщиках мусора и многое другое.

    У Java большое будущее!

    1.2 Установка

    Опубликованно: 21.07.2018, 21:58

    Последняя редакция, Andry: 11.11.2018 18:41

    LWJGL организован в виде модулей. Каждый модуль упакован как набор артефактов, где каждый артефакт имеет одно и то же название, но другой классификатор.

    • Название артефакта для модуля ядра LWJGL, это только lwjgl.
    • Название артефакта для модуля привязки lwjgl-<привязка>, например для модуля OpenGL будет lwjgl-opengl.

    Артефакты, основанные на классификаторе:

    • Нет классификатора: скомпилированные классы Java
    • Исходники: Java исходники
    • javadoc: документация по API
    • natives-<платформа>: нативные общедоступные библиотеки для соответствующей платформы

    Не все артефакты имеют нативные, и не все артефакты с нативным доступны на всех платформах.

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

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

    Загрузка LWJGL — Использование конфигуратора сборки

    Веб-сайт LWJGL предоставляет удобный конфигуратор для выбора тех частей библиотеки, которые вам нужно скачать. В этом разделе будет приведено краткое описание того, что делают отдельные части этого конфигуратора.

    Существует три отдельных варианта выпуска: Release(Релиз), Stable(Стабильный) и Nightly(Ночной). Если вы не знаете, что вам с этим делать, то тогда вы должны использовать Release, так как он будет более стабильным.

    Селектор Mode позволяет выбрать, нужный вам вариант скачивания библиотеки. Если вы планируете использовать IDE или вам нужны сами .jar файлы, выберите ZIP Bundle. Если вы собираетесь использовать maven или gradle, выберите соответствующий параметр для создания сценария сборки.

    Во время разработки рекомендуется использовать Maven/Gradle. ZIP Bundle рекомендуется для вашего приложения при создании сборки или установке.

    Нативные(Natives) не нужны для компиляции вашего проекта, но необходимы для его запуска. Таким образом, вам нужно получить нативное для всех платформ, на которых вы хотите запустить ваше приложение. Помните, что вам не нужно загружать нативное для всех платформ сразу. Вы можете скачать дополнительных нативные, когда будете готовы распространять(продавать) свой проект.

    Если вы впервые используете LWJGL, предварительные настройки(presets) Getting Started или Minimal OpenGL должны быть достаточными для начала работы с большинством обучающих программ. Кроме того, вы можете создать настраиваемую конфигурацию и выбрать именно те модули, которые вам нужны. Имейте в виду, что вы можете просмотреть описание различных модулей, отметив Show descriptions(Показывать описания) в разделе Options.

    Извлечение нативных (необязательно)

    Общедоступные нативные библиотеки LWJGL НЕ нужно извлекать из их .jar файлов. SharedLibraryLoader, который включен в LWJGL, делает это автоматически при выполнении.

    SharedLibraryLoader извлекает нативные один раз и повторно использует их от запуска к запуску. Нативное замещается только при обнаружении другой версии LWJGL.

    Папку для извлечения можно настроить с помощью Configuration.SHARED_LIBRARY_EXTRACT_DIRECTORY и Configuration.SHARED_LIBRARY_EXTRACT_PATH.

    Использование SharedLibraryLoader является необязательным. Например, пользовательский установщик для приложения может извлекать туземцев в определенное место. В таких случаях привычные -Djava.library.path и -Dorg.lwjgl.librarypath (или Configuration.LIBRARY_PATH) по-прежнему полностью поддерживаются.

    Настройка инструмента сборки или IDE

    Gradle или maven

    При использовании gradle или maven вы можете просто скопировать скрипт сборки, сгенерированный генератором, и использовать его для сборки вашего проекта. Обратите внимание, что при использовании gradle вы, вероятно, захотите добавить apply plugin: ‘java’ и apply plugin: ‘application’ в build.gradle.

    IntelliJ IDEA

    IDEA поддерживает Gradle/Maven проекты и делает их использование тривиальным. Для пользовательской конфигурации выполните следующие действия:

    1. Перейдите на страницу загрузки, выберите канал, выберите почтовый пакет, просмотрите параметры и выберите нужные вам привязки, затем нажмите «Создать пакет».
    2. Когда загрузка будет завершена, извлеките ее содержимое в свой проект.
    3. В IntelliJ перейдите в раздел Структура проекта> Библиотеки> Новая библиотека проектов. Добавьте все библиотеки LWJGL .jar (классы + туземцы) в библиотеку и добавьте библиотеку в качестве зависимости от вашего модуля (ов) проекта. Вам не нужно извлекать собственные библиотеки.
    4. Если вы также загрузили источники, добавьте соответствующие файлы .jar в качестве источников в библиотеку LWJGL. Вам не нужно загружать и прикреплять файлы javadoc .jar, IntelliJ генерирует javadoc непосредственно из источников.

    Если вы хотите точное соответствие поведения Maven/Gradle, вы можете создать две отдельные библиотеки:

    1. Один с .jar файлами классами + исходники, сделать его компиляцией зависимостей вашего модуля(ей).
    2. Один с нативными .jar файлами, сделать его с зависимостями времени выполнения вашего модуля(ей).

    Вы можете сделать это в Project Structure ▸ Modules ▸ выберите модуль ▸ вкладка Dependencies , изменив Scope каждой зависимости.

    NetBeans

    1. Загрузите LWJGL в качестве ZIP-пакета с помощью конфигуратора сборки и извлеките архив туда, где вы сможете его найти позже.
    2. Внутри Netbeans в разделе «Инструменты»> «Библиотеки» нажмите «Новая библиотека» … в нижнем левом углу.
    3. Назовите библиотеку что-то разумное, например «LWJGL 3.1.0», и нажмите ОК.
    4. В центре окна библиотеки теперь должны быть параметры для настройки библиотеки.
    5. На вкладке Classpath добавьте все файлы .jar из ранее загруженного ZIP-файла, за исключением тех, которые содержат источники или javadoc в их имени.
    6. (Необязательно) На вкладке «Источники» добавьте все файлы .jar с источниками в их имени. Это даст вам доступ к документации и исходному коду непосредственно из NetBeans. Источник можно просмотреть в редакторе нажатием Ctrl+Left при наведении курсора на функцию или класс, принадлежащий LWJGL.
    7. Создайте новый проект, выбрав Файл> Новый проект …. Выберите Java | Приложение Java в качестве типа проекта.
    8. Найдите проект в окне проекта (можно открыть с помощью Ctrl-1). Щелкните правой кнопкой мыши на «Библиотеки», выберите «Импорт», найдите созданную ранее библиотеку и выберите «Импортировать библиотеку», а затем «Добавить библиотеку».
    9. Убедитесь, что все работает по назначению, добавив следующую строку в ваш основной класс и запустив проект: System.out.println (org.lwjgl.Version.getVersion ()) ;. Это должно напечатать версию LWJGL, которую вы используете.

    Eclipse

    (вам понадобится хотя бы Eclipse Luna(4.4) или Eclipse Kepler(4.3) с патчем «Eclipse Java 8 Support (для Kepler SR2)», установленным для работы с LWJGL 3 в Eclipse)

    Eclipse поддерживает проекты Gradle/Maven, и настоятельно рекомендуется использовать их вместо ручной настройки проекта Eclipse. Однако, если вы предпочитаете настраивать собственный проект Eclipse, следуйте следующим инструкциям (работает с Eclipse Neon):

    1. Загрузите пакет ZIP с https://www.lwjgl.org/customize
    2. Когда загрузка будет завершена, извлеките ее содержимое в какой-либо каталог файловой системы, отныне называемый .
    3. В Eclipse перейдите в меню «Окно»> «Настройки» и в древовидном представлении слева найдите «Java»> «Путь сборки»> «Библиотеки пользователей»,
    4. Нажмите «Создать …» в диалоговом окне «Библиотеки пользователей». В открывшемся модальном диалоговом окне «Новая пользовательская библиотека» напишите «LWJGL3» в текстовом поле «Имя пользователя:» и нажмите «ОК». Недавно созданная библиотека «LWJGL3» должна отображаться в списке «Определенные пользовательские библиотеки:».
    5. Теперь выберите этот элемент в списке и нажмите «Добавить внешние JAR …». Это открывает стандартный диалог выбора файла ОС, позволяющий выбрать файлы * .jar, которые будут добавлены в путь к классам / путь сборки всех проектов, используя пользовательскую библиотеку LWJGL3. Перейдите в и выберите все * .jar-файлы, в которых нет -javadoc или -sources. Убедитесь, что вы не забыли файл lwjgl-natives- .jar и нажмите «Открыть».
    6. Это заполнит пользовательскую библиотеку LWJGL3 в списке соответствующими записями для всех выбранных файлов jar. Теперь вы можете оставить его, чтобы использовать LWJGL 3.
    7. Однако, если вы хотите иметь источники и JavaDocs, вам нужно будет выбрать каждую из записей, щелкнуть «Вложение источника: (Нет)» и «Изменить …». Откроется диалоговое окно «Конфигурация источника подключения». Здесь вы можете выбрать «Внешнее местоположение» и «Внешний файл …», чтобы выбрать соответствующий файл * -sources.jar.
    8. Чтобы фактически использовать пользовательскую библиотеку LWJGL3 в одном из ваших проектов, перейдите на вкладку «Путь сборки» вашего проекта и выберите вкладку «Библиотеки». Здесь нажмите «Добавить библиотеку …», выберите «Пользовательская библиотека» и отметьте «Пользовательскую библиотеку LWJGL3».
    9. Теперь вы настроены на использование LWJGL 3 в своем проекте.

    Другие инструменты

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


    Переведено для jmonkeyengine.ru, оригинал. 
    Автор перевода: Andry

    Введение в JavaDoc | Baeldung

    Если у вас есть несколько лет опыта работы в экосистеме Java, и вы заинтересованы в том, чтобы поделиться этим опытом с сообществом (и, конечно же, получать деньги за свою работу), загляните на страницу «Напишите для нас». . Ура, Евгений

    1. Обзор

    Хорошая документация по API - один из многих факторов, способствующих общему успеху программного проекта.

    К счастью, все современные версии JDK предоставляют инструмент Javadoc - для создания документации API из комментариев, присутствующих в исходном коде.

    Предварительные требования:

    1. JDK 1.4 (для последней версии плагина Maven Javadoc рекомендуется JDK 7+)
    2. Папка JDK / bin добавлена ​​в переменную среды PATH
    3. (необязательно) IDE со встроенными инструментами

    2. Комментарии Javadoc

    Начнем с комментариев.

    Структура комментариев Javadoc очень похожа на обычный многострочный комментарий , но ключевым отличием является дополнительная звездочка в начале:

      // Это однострочный комментарий
    
    / *
     * Это обычный многострочный комментарий
     * /
    
    / **
     * Это Javadoc
     * /  

    Комментарии в стиле Javadoc также могут содержать теги HTML.

    2.1. Формат Javadoc

    Комментарии Javadoc могут быть размещены над любым классом, методом или полем, которые мы хотим задокументировать.

    Эти комментарии обычно состоят из двух разделов:

    1. Описание того, что мы комментируем
    2. Отдельные теги блоков (отмеченные символом « @ »), которые описывают определенные метаданные.

    В нашем примере мы будем использовать некоторые из наиболее распространенных блочных тегов.Полный список тегов блоков можно найти в справочном руководстве.

    2.2. Документация Javadoc на уровне класса

    Давайте посмотрим, как будет выглядеть комментарий Javadoc на уровне класса:

      / **
    * Герой - это основная сущность, для которой мы будем использовать. . .
    *
    * Пожалуйста, ознакомьтесь с классом {@link com.baeldung.javadoc.Person}, чтобы узнать подлинную идентичность.
    * @author Капитан Америка
    *
    * /
    public class SuperHero extends Person {
        // поля и методы
    }  

    У нас есть краткое описание и два разных тега блока - автономный и встроенный:

    • Отдельные теги появляются после описания с тегом в качестве первого слова в строке, e.g., тег @author
    • Встроенные теги могут появляться где угодно и заключены в фигурные скобки , например, тег @link в описании

    В нашем примере мы также видим два типа используемых тегов блоков:

    • {@link} предоставляет встроенную ссылку на указанную часть нашего исходного кода
    • @author имя автора, добавившего класс, метод или поле, к которому добавлен комментарий

    2.3. Документация Javadoc на полевом уровне

    Мы также можем использовать описание без каких-либо тегов блоков, подобных этому, внутри нашего класса SuperHero :

      / **
     * Общеизвестное публичное имя героя
     * /
    частная строка heroName;  
    Для

    частных полей не будет сгенерирована документация Javadoc, если мы явно не передадим в команду Javadoc параметр -private .

    2.4. Документация Javadoc на уровне метода

    Методы могут содержать множество тегов блоков Javadoc.

    Давайте посмотрим на метод, который мы используем:

      / **
     * 

    Это простое описание метода. . . * Супермен! *

    * @param incomingDamage количество входящего урона * @return количество здоровья героя после атаки * @ см. HERO-402 * @since 1.0 * / public int успешноAttacked (int incomingDamage) { // заниматься вещами возврат 0; }

    Метод успешноAttacked содержит как описание, так и многочисленные автономные теги блоков.

    Существует множество блочных тегов, которые помогают создавать надлежащую документацию, и мы можем включать в себя всевозможные виды информации. Мы даже можем использовать в комментариях базовые HTML-теги.

    Давайте рассмотрим теги, с которыми мы столкнулись в приведенном выше примере:

    • @param предоставляет любое полезное описание параметра метода или входных данных, которые он должен ожидать
    • @return предоставляет описание того, что метод будет или может вернуть
    • @see создаст ссылку, аналогичную тегу {@link} , но больше в контексте ссылки, а не в строке
    • .
    • @since указывает, какая версия класса, поля или метода была добавлена ​​в проект
    • @version указывает версию программного обеспечения, обычно используемую с макросами% I% и% G%.
    • @throws используется для дальнейшего объяснения случаев, когда программное обеспечение ожидает исключения
    • @deprecated дает объяснение, почему код устарел, когда он мог быть устаревшим и какие есть альтернативы.

    Хотя оба раздела технически необязательны, нам понадобится хотя бы один, чтобы инструмент Javadoc мог сгенерировать что-нибудь значимое.

    3. Поколение Javadoc

    Чтобы сгенерировать наши страницы Javadoc, мы хотим взглянуть на инструмент командной строки, который поставляется с JDK, и плагин Maven.

    3.1. Инструмент командной строки Javadoc

    Инструмент командной строки Javadoc очень мощный, но с ним связана некоторая сложность.

    Выполнение команды javadoc без каких-либо опций или параметров приведет к ошибке и ожидаемым выходным параметрам.

    Нам нужно хотя бы указать, для какого пакета или класса мы хотим, чтобы документация была сгенерирована.

    Давайте откроем командную строку и перейдем в каталог проекта.

    Предполагая, что все классы находятся в папке src в каталоге проекта:

      [адрес электронной почты защищен]: ~ $ javadoc -d doc src \ *  

    Это создаст документацию в каталоге с именем doc , как указано с флагом - d . Если существует несколько пакетов или файлов, нам нужно будет предоставить их все.

    Использование IDE со встроенными функциями, конечно, проще и обычно рекомендуется.

    3.2. Документация Javadoc с подключаемым модулем Maven

    Мы также можем использовать плагин Maven Javadoc:

      <сборка>
        <плагины>
            <плагин>
                 org.apache.maven.plugins 
                 maven-javadoc-plugin 
                <версия> 3.0,0 
                <конфигурация>
                     1.8 
                     1.8 
                
                <теги>
                ...
                
            
        
      

    В базовом каталоге проекта мы запускаем команду для создания наших документов Javadocs в каталог в target \ site:

      [адрес электронной почты защищен]: ~ $ mvn javadoc: javadoc  

    Плагин Maven очень мощный и упрощает создание сложных документов.

    Давайте теперь посмотрим, как выглядит сгенерированная страница Javadoc:

    Мы видим древовидное представление классов, которые расширяет наш класс SuperHero . Мы можем видеть наше описание, поля и метод, а также можем щелкать ссылки для получения дополнительной информации.

    Детальный вид нашего метода выглядит так:

    3.3. Пользовательские теги Javadoc

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

    Для этого нам просто нужно включить опцию -tag в нашу командную строку Javadoc в формате : :

    .

    Чтобы создать настраиваемый тег с именем @location , разрешенный где угодно, который отображается в заголовке «Известные места» в нашем сгенерированном документе, нам нужно запустить:

      [электронная почта защищена]: ~ $ javadoc -tag location: a: "Известные места:" -d doc src \ *  

    Чтобы использовать этот тег, мы можем добавить его в раздел блоков комментария Javadoc:

      / **
     * Это пример...
     * @location Нью-Йорк
     * @ возвращает бла бла
     * /  

    Плагин Maven Javadoc достаточно гибок, чтобы также позволять определения наших пользовательских тегов в нашем pom.xml .

    Чтобы настроить тот же тег для нашего проекта, мы можем добавить следующее в раздел нашего плагина:

      ...
    <теги>
        <тег>
             местоположение 
             а 
             Достопримечательности: 
        
    
    ...  

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

    4. Заключение

    В этом кратком вводном руководстве рассказывается, как писать базовые документы Javadoc и создавать их с помощью командной строки Javadoc.

    Более простой способ создания документации - использовать любые встроенные параметры IDE или включить плагин Maven в наш файл pom.xml и выполнить соответствующие команды.

    Примеры кода, как всегда, можно найти на GitHub.

    Chapter10.Documentation with Javadoc

    Документирование вашего кода имеет решающее значение для того, чтобы помочь другим понять его и даже напомнить себе, как работают ваши собственные старые программы. К сожалению, большая часть внешней документации легко устареет по мере изменения программы. По этой причине полезно писать документацию в виде комментариев в самом коде, где они могут быть легко обновлены другими изменениями. Javadoc - это инструмент документации, который определяет стандартный формат для таких комментариев и который может генерировать файлы HTML для просмотра документации через веб-браузер.(В качестве примера см. Документацию Oracle Javadoc для библиотек Java по адресу http://download.oracle.com/javase/6/docs/api/.)

    Вы можете легко запускать Javadoc для своих программ из DrJava, используя Команды «Javadoc All Documents» и «Preview Javadoc for Current Document» в меню «Инструменты». Эти команды будут генерировать HTML-файлы Javadoc из написанных вами комментариев и отображать их в браузере. В этой главе дается краткий обзор этих команд и того, как писать комментарии Javadoc.Более подробную информацию о написании комментариев Javadoc можно найти в Интернете по адресу http://www.oracle.com/technetwork/java/javase/documentation/index-137868.html.

    Как правило, комментарии Javadoc - это любые многострочные комментарии (« / ** ... * / »), которые помещаются перед объявлениями класса, поля или метода. Они должны начинаться с косой черты и двух звездочек и могут включать специальные теги для описания таких характеристик, как параметры метода или возвращаемые значения. Файлы HTML, созданные Javadoc, будут описывать каждое поле и метод класса, используя комментарии Javadoc в самом исходном коде.Примеры различных комментариев Javadoc перечислены ниже.

    Простые комментарии. Обычные комментарии Javadoc могут быть помещены перед объявлением любого класса, поля или метода, чтобы описать его назначение или характеристики. Например, следующий простой класс Student имеет несколько комментариев Javadoc.

    / **
     * Представляет ученика, зачисленного в школу.
     * Студент может быть зачислен на многие курсы.
     * /
    public class Student {
    
      / **
       * Имя и фамилия этого студента.
       * /
      частное строковое имя;
    
      / **
       * Создает нового ученика с данным именем.* Имя должно включать как первое, так и
       * Фамилия.
       * /
      public Student (String name) {
        this.name = имя;
      }
    
    }
     

    Использование тегов. Теги могут использоваться в конце каждого комментария Javadoc для предоставления более структурированной информации об описываемом коде. Например, большинство комментариев Javadoc для методов включают теги « @param » и « @return », когда это применимо, для описания параметров метода и возвращаемого значения. За тегом « @param » должно следовать имя параметра, а затем описание этого параметра.За тегом « @return » следует просто описание возвращаемого значения. Примеры этих тегов приведены ниже.

      / **
       * Получает имя и фамилию этого ученика.
       * @ вернуть имя этого студента.
       * /
      public String getName () {
        возвращаемое имя;
      }
    
      / **
       * Изменяет имя этого ученика.
       * Это может потребовать длительного судебного процесса.
       * @param newName Новое имя этого ученика.
       * Должны включать оба первых
       * и фамилия.* /
      public void setName (String newName) {
        name = newName;
      }
     

    Другие общие теги включают « @throws e » (для описания некоторого исключения «e», которое генерируется методом) и « @see #foo » (для предоставления ссылки на поле или метод с именем «foo ").

    Блог Стивена Колебурна: стандарты кодирования Javadoc

    Javadoc - это ключевая часть программирования на Java, но относительно мало обсуждается, что делает Стиль Javadoc - стандарт кодирования.

    Стандарт кодирования Javadoc

    Это стандарты, которые я обычно использую при написании Javadoc.Поскольку личные вкусы различаются, я попытался объяснить некоторые причины моего выбора. Имейте в виду, что это больше касается форматирования Javadoc, чем содержимого Javadoc.

    Есть руководство Oracle который длиннее и детальнее, чем этот. В большинстве случаев они сходятся во мнениях, однако эти рекомендации более четко относятся к тегам HTML, два пробела в @param и нулевой спецификации и отличаются длиной строки и расположением предложения.

    Каждое из приведенных ниже рекомендаций состоит из краткого описания правила и объяснения, которое может включать в себя пример:

    Написать Javadoc для чтения как исходный код

    Когда мы думаем о "Javadoc", мы часто думаем о онлайн-страницы Javadoc HTML.Однако это не единственный способ использования Javadoc. Ключевой способ освоения Javadoc - это чтение исходного кода, написанного вами или вашей командой, или сторонние библиотеки. Сделать Javadoc доступным для чтения как исходный код критически важно, и эти стандарты руководствуются этим принципом.

    Общедоступные и охраняемые

    Все общедоступные и защищенные методы должны быть полностью определены с помощью Javadoc. Пакетные и частные методы не обязательны, но могут принести пользу.

    Если метод переопределяется в подклассе, Javadoc должен присутствовать только если он говорит что-то отличное от исходного определения метода.Аннотацию @Override следует использовать для указания читателям исходного кода что Javadoc наследуется в дополнение к своему обычному значению.

    Используйте стандартный стиль для комментария Javadoc

    Javadoc требует только "/ **" в начале и "* /" в конце. В дополнение к этому используйте одну звездочку на каждой дополнительной строке:

     / **
       * Стандартный комментарий.
       * /
      общественные ...
    
      / ** Сжатый комментарий. * /
      общественные ... 

    Не используйте '** /' в конце Javadoc.

    Использовать простые теги HTML, недопустимый XHTML

    Javadoc использует теги HTML для идентификации абзацев и других элементов. Многие разработчики приходят к мысли, что XHTML - лучший вариант, гарантирующий, что все теги открываются и закрываются правильно. Это ошибка. XHTML добавляет множество дополнительных тегов, которые затрудняют чтение Javadoc как исходного кода. Парсер Javadoc прекрасно интерпретирует неполный суп HTML-тегов.

    Используйте один тег

    между абзацами

    Для более длинного Javadoc всегда требуется несколько абзацев.Это, естественно, приводит к вопросу о том, как и где добавить теги абзацев. Поместите один тег

    в пустую строку между абзацами:

     / **
       * Первый параграф.
       * 

    * Второй абзац. * Может быть на нескольких строках. *

    * Третий абзац. * / общественные ...

    Использовать один тег

  • для элементов в списке

    Списки полезны в документации Javadoc при объяснении набора параметров, вариантов или проблем. Эти стандарты помещают один тег

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

     / **
       * Первый параграф.
       * 

      *
    • первый элемент *
    • второй элемент *
    • третий элемент *

    * Второй абзац. * / общественные ...

    Дайте короткое первое предложение

    Первое предложение, обычно заканчивающееся точкой, используется в документации Javadoc следующего уровня. Таким образом, он несет ответственность за подведение итогов метода или класса для читателей, просматривающих класс или пакет.Для этого первое предложение должно быть четким, резким и, как правило, коротким.

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

    На старте рекомендуется использовать форму от третьего лица. Например, «Получает фу», «Устанавливает полосу» или «Потребляет базу». Избегайте формы от второго лица, например «Get the foo».

    Используйте "this" для ссылки на экземпляр класса .

    Обращаясь к экземпляру документируемого класса, используйте "this" для ссылки на него.Например, «Возвращает копию этого foo с обновленным значением bar».

    Стремитесь к коротким однострочным предложениям

    По возможности помещайте предложения Javadoc в одну строку. Обеспечьте гибкость в длине строки, отдавая предпочтение от 80 до 120 символов, чтобы это работало.

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

     / **
       * Это первый абзац на одной строке.* 

    * Это первое предложение второго абзаца на одной строке. * Это второе предложение второго абзаца на одной строке. * Это третье предложение второго абзаца, которое немного длиннее, поэтому было * разделить на вторую строку, если это имеет смысл. * Это четвертое предложение, с которого начинается новая строка, хотя наверху есть пробел. * / общественные ...

    Используйте @link и @code с умом

    Многие описания Javadoc ссылаются на другие методы и классы.Наиболее эффективно этого можно достичь с помощью функций @link и @code.

    Функция @link создает видимую гиперссылку в сгенерированном документе Javadoc на цель. Цель @link - это одна из следующих форм:

     / **
       * Первый параграф.
       * 

    * Ссылка на класс с именем Foo: {@link Foo}. * Ссылка на метод bar в классе с именем Foo: {@link Foo # bar}. * Ссылка на метод baz в этом классе: {@link #baz}. * Ссылка, определяющая текст гиперссылки после пробела: {@link Foo the Foo class}.* Ссылка на перегрузку метода обработки метода {@link Foo # bar (String, int)}. * / общественные ...

    Функция @code предоставляет раздел шрифта фиксированной ширины, идеально подходящий для ссылок на методы и имена классов. Хотя ссылки @link проверяются компилятором Javadoc, ссылки @code - нет.

    Используйте @link только для первой ссылки на конкретный класс или метод. Используйте @code для последующих ссылок. Это позволяет избежать чрезмерного загромождения документации Javadoc гиперссылками.

    Никогда не используйте @link в первом предложении

    Первое предложение используется в документации Javadoc более высокого уровня.Добавление гиперссылки в первое предложение делает документацию более высокого уровня более запутанной. При необходимости всегда используйте @code в первом предложении. @link можно использовать, начиная со второго предложения / абзаца.

    Не используйте @code для null, true или false

    Понятия null, true и false очень распространены в Javadoc. Добавление @code для каждого случая является обузой как для читателя, так и для автора Javadoc и не добавляет реальной ценности.

    Используйте @param, @return и @throws

    Почти все методы принимают параметр, возвращают результат или и то, и другое.Функции @param и @return определяют эти входы и выходы. Функция @throws определяет возникшие исключения.

    Записи @param следует указывать в том же порядке, что и параметры. @Return должен быть после записей @param, за которым следует @throws.

    Используйте @param для дженериков

    Если у класса или метода есть параметры универсального типа, то они должны быть задокументированы. Правильный подход - это тег @param с именем параметра , где T - это имя параметра типа.

    Используйте одну пустую строку перед @param

    Между текстом Javadoc и первым @param должна быть одна пустая строка. или @return. Это улучшает читаемость исходного кода.

    Рассматривайте @param и @return как фразу

    @Param и @return следует рассматривать как фразы, а не полные предложения. Они должны начинаться со строчной буквы, обычно со слова «the». Они не должны заканчиваться точкой. Это улучшает читаемость исходного кода и при его создании.

    Обрабатывать @throws как условие if

    За функцией @throws обычно следует "если", а остальная часть фраза, описывающая состояние. Например, «@throws IllegalArgumentException, если файл не может быть найден». Это улучшает читаемость исходного кода и при его создании.

    @param должно быть два пробела после имени параметра

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

     / **
       * Текст Javadoc.
       *
       * @param foo параметр foo
       * @param bar параметр бара
       * @ вернуть содержимое базы
       * /
      общедоступный процесс String (String foo, String bar) {...} 

    Определите нулевую обработку для всех параметров и типов возврата

    Принимает ли метод на входе значение NULL или может возвращать значение NULL, является важной информацией. для построения больших систем.Все непримитивные методы должны определять свою нулевую толерантность в @param или @return. По возможности следует использовать некоторые стандартные формы, выражающие это:

    • «not null» означает, что null не принимается, и передача null будет вероятно, вызовет исключение, обычно NullPointerException
    • «может быть нулевым» означает, что может быть передано значение null. В целом поведение из переданных в null должно быть определено
    • «null обрабатывается как xxx» означает, что ввод null эквивалентен указанному значению
    • «null возвращает xxx» означает, что ввод null всегда возвращает указанное значение.

    При таком определении должно быть , а не @throws для NullPointerException .

     / **
       * Текст Javadoc.
       *
       * @param foo параметр foo, а не null
       * @param bar параметр bar, null возвращает null
       * @ return the baz content, null, если не обрабатывается
       * /
      общедоступный процесс String (String foo, String bar) {...} 

    Хотя может возникнуть соблазн определить поведение обработки нулевого значения в одном центральном месте, например, класс или пакет Javadoc, это гораздо менее полезно для разработчиков. Документация Javadoc на уровне метода появляется в среде IDE при нормальном кодировании, тогда как класс Документация Javadoc на уровне пакета требует отдельного шага «поиск и изучение».

    Если применимо, могут быть добавлены и другие простые ограничения, например «not empty, not null». Примитивные значения могут указывать свои границы, например «от 1 до 5» или «не отрицательно».

    Спецификации требуют примечания по реализации

    Если вы пишете более формальную спецификацию, которая будет реализована третьими сторонами, рассмотрите возможность добавления раздела «Примечания по реализации». Это дополнительный раздел, обычно на уровне класса, который определяет любое поведение требуется реализациями, которые не указаны иначе, или не представляют общего интереса.См. Этот пример.

    Избегайте @author

    Функцию @author можно использовать для записи авторов класса. Этого следует избегать, поскольку он обычно устарел и может способствовать владению кодом отдельным лицом. Система управления версиями намного лучше подходит для записи авторов.

    Примеры

    В репозитории ThreeTen есть еще несколько полных Примеры

    Сводка

    Надеюсь, эти предложения помогут вам лучше писать Javadoc.Не стесняйтесь не соглашаться или указывать на альтернативные стандарты.

    документов Javadocs | IntelliJ IDEA

    Комментарии к документации также доступны на JavaScript, Python, Ruby и PHP.

    Для комментариев документации IntelliJ IDEA предоставляет автозавершение, которое включено по умолчанию.

    Отключить автоматические комментарии

    • В диалоговом окне «Настройки / Предпочтения» Ctrl + Alt + S перейдите к и снимите флажок «Вставить заглушку комментария к документации».

    Добавьте javadoc с помощью контекстных действий

    • Поместите курсор в объявление в редакторе, нажмите Alt + Enter и выберите Добавить Javadoc из списка.

    1. Поместите курсор в класс, метод, функцию или поле и нажмите Ctrl + Shift + A .

    2. Введите fix doc comment и нажмите Введите .

    IntelliJ IDEA добавляет недостающую заглушку документации с соответствующими тегами.

    Для комментариев метода новая заглушка комментария содержит необходимые теги ( @param тегов для каждого параметра метода, @return или @throws ).

    В Kotlin теги @param и другие не генерируются, потому что рекомендуемый стиль требует включения описания параметров и возвращаемых значений непосредственно в комментарий документации.

    Информацию о том, как документировать код Kotlin, см. В документации Kotlin.

    Исправить javadoc

    Если подпись метода была изменена, IntelliJ IDEA выделяет тег, который не соответствует подписи метода, и предлагает быстрое исправление. Нажмите Alt + Enter , чтобы применить исправление.

    Вы также можете обновить существующий комментарий javadoc, чтобы учесть изменения в объявлении, используя действие Исправить комментарий документа:

    1. Поместите курсор в класс, метод, функцию или поле и нажмите Ctrl + Shift + А .

    2. Введите fix doc comment и нажмите Введите .

    Визуализация документации Javadocs

    IntelliJ IDEA позволяет отображать документы Javadocs в редакторе. Визуализированные комментарии легче читать, и они не перегружают ваш код лишними тегами.

    Щелкните в желобе рядом с нужным комментарием в документации (или нажмите Ctrl + Alt + Q ), чтобы переключить визуализированный вид; нажмите, чтобы отредактировать комментарий.

    Визуализированные документы Javadocs позволяют щелкать ссылки, чтобы перейти к веб-страницам, на которые есть ссылки, или просматривать быструю документацию по указанным темам.

    Чтобы изменить размер шрифта, щелкните правой кнопкой документ Javadoc в редакторе и выберите «Настроить размер шрифта» в контекстном меню. Обратите внимание, что визуализированные комментарии используют тот же размер шрифта, что и всплывающее окно быстрой документации.

    Визуализация документации Javadoc по умолчанию

    Вы можете настроить среду IDE так, чтобы она всегда отображала документы Javadoc в редакторе.

    • Щелкните правой кнопкой мыши значок в желобе (или) и включите параметр «Визуализировать все».

      В качестве альтернативы, в диалоговом окне «Настройки / Предпочтения» Ctrl + Alt + S выберите и включите параметр «Визуализировать комментарии документации».

    Чтобы отредактировать визуализированные документы Javadoc, щелкните значок в полосе рядом с комментарием.

    Просмотр документации Javadocs в редакторе

    • Наведите указатель мыши на необходимый символ, чтобы просмотреть его документацию, или поместите курсор на символ и нажмите Ctrl + Q ().

      Нажмите Ctrl + Q еще раз, чтобы переключаться между всплывающим окном и панелью инструментов.

    Щелкните всплывающее окно, чтобы изменить размер шрифта, отобразить панель инструментов быстрой документации или перейти к исходному коду.

    Для получения дополнительной информации см. Быструю документацию.

    Создание ссылки Javadoc

    IntelliJ IDEA предоставляет утилиту, которая позволяет вам создавать ссылку Javadoc для вашего проекта.

    1. В главном меню выберите.

    2. В открывшемся диалоговом окне выберите область - набор файлов или каталогов, для которых вы хотите создать ссылку, и установите выходной каталог, в котором будет размещена сгенерированная документация.

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

    3. Используйте ползунок, чтобы определить уровень видимости элементов, которые будут включены в созданную документацию. Выберите один из следующих вариантов:

      • Частный: для включения всех классов и членов в ссылку.

      • Пакет: включает в себя все классы и члены, кроме частных.

      • Защищено: включить общедоступные и защищенные классы и члены.

      • Public: для включения только общедоступных классов и членов.

    4. Вы можете указать языковой стандарт (например, en_US.UTF-8 ), аргументы командной строки и максимальный размер кучи.

    5. Щелкните OK, чтобы создать ссылку.

    Укажите диалоговое окно «Создать область действия JavaDoc»

    В диалоговом окне вызывается служебная программа JavaDoc.Элементы управления диалогового окна соответствуют параметрам и тегам этой утилиты.

    Элемент Описание
    Создание области JavaDoc

    Используйте эту область, чтобы указать подмножество файлов, папок и пакетов, для которых должен быть создан JavaDoc.

    Этой областью может быть весь проект, недавно измененные файлы, текущий файл, настраиваемая область и т. Д.

    Включить источники тестов Включить комментарии документации для теста в сгенерированный JavaDoc.
    Включить JDK и источники библиотеки в -sourcepath Если этот флажок установлен, то пути к исходным файлам JDK и библиотеки будут переданы в утилиту JavaDoc. Подробную информацию см. В документации.
    Включить ссылку на документацию JDK

    Если этот флажок установлен, ссылки на классы и пакеты из JDK будут преобразованы в ссылки, что соответствует использованию параметра -link утилиты JavaDoc.

    Этот флажок доступен только в том случае, если ссылка на онлайн-документацию указана на вкладке «Пути документации» в настройках SDK.

    Подробные сведения см. В документации JavaDoc.

    Выходной каталог

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

    Обратите внимание, что если выходной каталог не указан, кнопка OK неактивна.

    Slider

    Укажите уровень видимости элементов, которые вы хотите включить в сгенерированную документацию:

    • Частный: выберите этот уровень, чтобы включить все классы и элементы. Уровень соответствует параметру -private JavaDoc.

    • Пакет: выберите этот уровень, чтобы включить все классы и члены, кроме частных. Уровень соответствует параметру -package JavaDoc.

    • Защищено: выберите этот уровень, чтобы включить только общедоступные и защищенные классы и члены. Уровень соответствует защищенному параметру JavaDoc .

    • Общедоступный: выберите этот уровень, чтобы включить только общедоступные классы и члены. Уровень соответствует параметру -public JavaDoc.

    Сгенерировать дерево иерархии Сгенерировать иерархию классов. Если этот флажок снят, параметр -notree передается в JavaDoc.
    Создать панель навигатора Создать панель навигатора. Если этот флажок снят, параметр -nonavbar передается в JavaDoc.
    Сгенерировать индекс Сгенерировать индекс документации. Если этот флажок снят, параметр -noindex передается в JavaDoc.
    Отдельный индекс для каждой буквы

    Создает отдельный индексный файл для каждой буквы. Если этот флажок снят, параметр -splitindex передается в JavaDoc.

    Флажок доступен, только если установлен флажок Создать индекс.

    @use Задокументируйте использование класса и пакета. Если этот флажок установлен, он соответствует параметру -use JavaDoc.
    @author Включите абзацы @author .Если этот флажок установлен, он соответствует параметру -author JavaDoc.
    @version Включите абзацы @version . Если этот флажок установлен, он соответствует параметру JavaDoc -version .
    @deprecated Включите информацию @deprecated . Когда флажок снят, параметр -nodeprecated передается в JavaDoc.
    устаревший список

    Создание устаревшего списка.Когда флажок снят, параметр -nodeprecatedlist передается в JavaDoc.

    Флажок доступен, только если установлен флажок @deprecated.

    Языковой стандарт Введите желаемый языковой стандарт.
    Другие аргументы командной строки Введите дополнительные аргументы для передачи в JavaDoc. Используйте синтаксис командной строки.
    Максимальный размер кучи (МБ) Введите максимальный размер кучи в МБ, который будет использоваться виртуальной машиной Java для запуска JavaDoc.
    Открыть сгенерированную документацию в браузере Автоматически открывать сгенерированный JavaDoc в браузере.

    Устранение неполадок

    javadoc: error - Неверное имя языкового стандарта: en_US.UTF-8

    Очистите поле Locale. В поле Другие аргументы командной строки добавьте -encoding utf8 -docencoding utf8 -charset utf8 .

    -encoding определяет кодировку исходных файлов. -docencoding определяет кодировку выходных файлов HTML, а -charset - это кодировка, указанная в разделе заголовка HTML выходных файлов.

    Последнее изменение: 8 марта 2021 г.

    javadoc-Генератор документации Java API

    Этого параметра нет в 1.2Beta4, но он будет в последней версии 1.2.
    Создайте ссылки на существующую документацию, созданную с помощью javadoc, для классов , а не документируется в текущем запуске javadoc. Это позволяет, например, сторонняя документация для ссылки на java. * документация по http://java.sun.com . Другое использование - выполнить javadoc для одного набора пакетов, затем снова запустить его для другого набор пакетов, создавая перекрестные ссылки между обоими наборами.Еще один использование - выполнить javadoc для одного набора пакетов, а затем запустить его снова на подмножестве этих пакетов и поддерживать ссылки на весь набор.

    Укажите -ссылку с URL-адресом на внешнюю документацию:

    • docURL - это URL-адрес внешней документации, созданной с помощью javadoc. вы хотите разместить ссылку. Это местоположение может быть относительным или абсолютным URL-адресом.

    Чтобы эти ссылки переходили на действующие страницы, вы должны знать, где они HTML-страницы расположены, и укажите это местоположение с помощью docURL .

    Вы можете указать несколько вариантов -ссылка для ссылки на любой номер внешних сгенерированных документов.

    Без этой опции javadoc не создает ссылки на документация для внешних ссылок, потому что Javadoc делает не знаю, существует ли (или где) эта документация.

    Используйте опцию -ссылка следующим образом:

    • Опустите опцию -link для javadoc, чтобы создавать ссылки только на API в документации, которую он генерирует в текущий пробег.
    • Включите опцию -ссылка для javadoc, чтобы также создавать ссылки на документация по адресу docURL для внешние ссылочные классы.

    Обратите внимание, что для этого параметра требуется доступ к URL-адресу при запуске javadoc. Таким образом, если URL-адрес находится во всемирной паутине, у вас должно быть подключение к Интернету. при формировании документации. Если вы этого не сделаете, вы можете использовать -ссылка оффлайн вместо.

    Эта опция требует, чтобы файл с именем список-пакетов , который создается Javadoc, существует по URL-адресу, который вы указываете с помощью -ссылка .Javadoc использует этот файл, чтобы определить, какие пакеты задокументированы в этом месте. Этот файл более подробно описан ниже.

    Укажите разные параметры ссылки для каждого внешнего документа, на который нужно ссылаться:

    javadoc -ссылка docURL1 -ссылка docURL2 ... -ссылка docURLn mypackage

    где docURL1 , docURL2 , ... docURLn точка соответственно к корням внешних документов, каждый из которых содержит файл с именем package-list .Файл представляет собой простой текстовый файл, перечисляет имена пакетов, задокументированных в этом месте. Для java. * Это список будет:

      java.applet
      java.awt
      java.awt.color
      и т.п.
     
    Список пакетов для Java Platform 1.2 API находится по адресу http://java.sun.com/products/jdk/1.2/docs/api/package-list.

    Обратите внимание, что этот параметр требует, чтобы javadoc имел URL-адрес для подключения к файлу. когда javadoc запущен, чтобы получить доступ к файлу package-list .

    Например:

    javadoc -ссылка http: // java.sun.com/products/jdk/1.2/docs/api
     
    Когда javadoc запускается без параметра -link , поскольку он генерирует документацию, когда он встречает имя, принадлежащее внешнему ссылочный класс, он печатает имя без ссылки. Однако, когда используется опция -ссылка , Javadoc ищет package-list файл в указанном месте docURL для пакета с таким именем. Если он находит имя пакета, он ставит перед именем префикс этого URL-адреса. (Если URL-адрес относительный, а параметр каталога назначения -d - относительный, Javadoc добавляет относительный путь к целевому каталогу к URL-адресу так что ссылки будут работать из целевого каталога.)

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

    Файл списка пакетов создается, но остается пустым, если аргумент javadoc равен исходные файлы, а не пакеты.

    Обратите внимание, что при перекрестном связывании двух или более документов может потребоваться "начальная загрузка". которые ранее не создавались. Другими словами, если список пакетов не существует ни для одного документа, при запуске javadoc для первого документа список пакетов для второго документа еще не существует. Следовательно, чтобы создать внешние ссылки, вы должны повторно сгенерировать первый документ. после создания второго документа.

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

    Другой вариант использования -ссылка - это когда вы ранее не запускали javadoc на исходное дерево, и теперь, в отдельном прогоне, вы хотите обновить только часть дерева. Просто установите -link и -d на один и тот же относительный путь.

     javadoc -d html -link html mypackage
     
    Справочная информация: как правило, при запуске javadoc потенциал для создания ссылок для имен, которые появляются в его сгенерированные страницы: в подписях, тегах @see, тегах {@link}, сводках, иерархиях, обзор и указатель.Некоторые из этих ссылок перейдут на страницы, созданные в текущем прогоне, в то время как другие ссылки потенциально будет переходить на страницы, не созданные в текущем прогоне. Этой опции нет в 1.2Beta4, но она будет в последней версии 1.2
    Эта опция создает ссылки на документацию для имен внешних ссылок классы, где:
    • docURL - это URL-адрес внешней документации, созданной javadoc. вы хотите разместить ссылку. Это местоположение может быть относительным или абсолютным URL-адресом.
    • packagelistURL - это URL-адрес файла списка пакетов для этого документация. При необходимости вы можете создать этот файл вручную.

    Этот вариант является разновидностью - ссылка . Ты можешь использовать -linkoffline , если файл списка пакетов не существует по адресу docURL во время запуска javadoc. Если вы знаете, на какие имена пакетов будет ссылаться ваш документ, и где этот документ будет находиться, он позволяет вам сгенерировать документация с этими внешними ссылками до того, как файл списка пакетов действительно существует в этом месте.Это позволяет вам использовать вашу собственную копию package-list для создания документацию с соответствующими ссылками.

    Это полезно, когда вам нужно создать документацию, содержащую ссылки к новой внешней документации, названия пакетов которой вы знаете, но не пока не опубликовано. Это позволяет двум компаниям выпускать свою документацию. одновременно. Это также позволяет вам создавать документацию, которая ссылки на внешнюю документацию, в которой нет файла со списком пакетов (возможно, потому что он был создан с помощью Javadoc 1.2 Beta3).

    Обратите внимание, что эта опция не требует доступа к URL-адресу документации. когда вы запускаете javadoc. Таким образом, если URL-адрес находится во всемирной паутине, вам не нужно подключение к Интернету при создании документации.

    Как показано ниже, чтобы использовать эту опцию, укажите docURL1 , расположение документации, созданной javadoc для классы, на которые ссылаются внешние, и packagelistURL1 , расположение его файла списка пакетов. Если они находятся в одном месте, вместо этого вы можете просто использовать - ссылку .Включаю - ссылка оффлайн один раз для каждого сгенерированного документа, на который вы хотите сослаться:

    javadoc -linkoffline docURL1 packagelistURL1 -linkoffline docURL2 packagelistURL2

    Для пользователей BlueJ: как создавать пакеты; как использовать javadoc и jar

    I. Создание пакетов в BlueJ

    Если вы используете BlueJ для выполнения заданий CIS300, имейте в виду что BlueJ требует особой процедуры для построения и используя пакеты.
    Загрузки

    Во-первых, , пожалуйста, убедитесь, что вы используете BlueJ версии 1.1.4 или новее. (Для этого также необходимо установить `` Java 2 Standard Edition '', JDK 1.3 или новее, также.) Видеть http://www.bluej.org/download/download.html для загрузки последний выпуск BlueJ и получить информацию о загрузке соответствующая версия Java.

    Сборка пакетов

    Скажите, что вы хотите использовать BlueJ для создания папки Assign1, который содержит пакет с именем P.В пакете P вы хотите вставить класс C.java. Вот что ты делаешь:

    1. Щелкните меню Project и щелкните его Новый проект Пункт меню. Появится диалоговое окно с файлом, в котором вас попросят имя папки, которую вы хотите создать --- введите Assign1 и нажмите кнопку создать .

      Важно: Вы можете указать BlueJ, где на вашем диске вы хотите для создания папки Assign1. Помните, где вы его создали - это будет облегчить себе жизнь, когда пришло время сдавать свои работы на оценку.

    2. В результате предыдущего шага BlueJ создает новую папку с именем Assign1, и он открывает новое окно, представляющее папку тебе. (Увы, в BlueJ папка (каталог) называется `` проектом ''!)

      Теперь мы готовы создать пакет P: В окне Assign1, щелкните меню Edit и щелкните его New Package пункт меню. Появится диалоговое окно с запросом имени пакет --- введите P и нажмите ОК.

    3. В результате предыдущего шага папка (пакет) с именем P был создан внутри папки Assign1.
    4. Теперь вы готовы включить класс C в пакет P. Это можно сделать двумя способами:

      1. Напишите с нуля:

      На этом этапе вы можете редактировать и компилировать различные java-файлы как обычно.

      2. Скопируйте его откуда-нибудь:

      Скажите, что класс C уже записан и сохранен как файл, C.java, в другая папка. Вы можете скопировать его в пакет с помощью

      • дважды щелкните папку P; это открывает пакет и отображает новый окно.
      • щелкните меню Edit , а затем щелкните Добавить класс из пункта меню «Файл» .
      • Появится диалоговое окно с файлом; используйте это, чтобы найти C.java; как только вы его найдете, нажмите кнопку Добавить .

    В более новых выпусках BlueJ вы можете скопировать содержимое всего пакета сразу: скажите, что вы хотите скопировать полностью упаковать Q в Assign1:

    1. Откройте окно для Assign1.
    2. Выберите Edit , а затем New Package .Введите имя, Q, в диалог.
    3. Откройте окно для Q; выберите Project , а затем Импорт . Используйте диалоговое окно файла, чтобы найти папку (пакет) с именем Q в вашей файловой системе.
    Затем BlueJ скопирует все классы из папки Q в Пакет Q BlueJ, который вы только что создали.

    II. Использование javadoc и jar

    javadoc
    Последняя версия BlueJ позволяет запускать javadoc: Откройте пакет, щелкните меню Инструменты и выберите пункт меню Project Documentation .Это запускает javadoc в открытом пакете и создает новую папку с документация с именем doc на та же папка, в которой живет сам пакет.

    Важно: Нет гарантии, что реализация BlueJ javadoc работает правильно. Если вы получили сообщение об ошибке из BlueJ, то вы должны сгенерировать свою документацию, запустив javadoc из командного окна --- см. ниже.

    банка

    Мы используем jar для подготовки задания CIS300 к отправке.Более новые версии BlueJ позволяют создавать файлы jar.

    К сожалению, файл jar, который создает BlueJ, не сохраняет папка проекта, когда баночка-кольцо. Это делает результат открытия файла jar беспорядочным, потому что папка проекта потеряна, а внутренности разбросаны по диску. По этой причине вы должны использовать окно командной строки (`` окно MS-DOS '') для создание файла jar.

    Как использовать javadoc из командного окна:

    Чтобы использовать javadoc в папке проекта Assign1, выполните следующие действия:

    1. Откройте окно командной строки.(Для этого нажмите «Пуск», затем нажмите «Все программы», затем «Аксессуары», затем ComandPrompt.)
    2. В окне несколько раз тип команда cd для перехода в каталог где живет Assign1. (Если вы никогда не использовали компакт-диск команды, спросите друга, ТА или инструктора.
    3. Когда вы найдете папку Assign1, введите cd Assign1. Когда вы набираете dir, вы увидите имена всех пакетов в папке.
    4. Для генерации веб-страниц API для всех классов в пакет P, введите javadoc -classpath.п
    Если это не работает должным образом (например, вы видите сообщение, `javadoc 'не распознается ...), см. примечание ниже.
    Как использовать jar из командного окна:

    Скажем, мы хотим заархивировать папку проекта Assign1 в jar файл. Чтобы использовать jar, сделайте следующее:

    1. Откройте окно командной строки, как описано выше.
    2. Используйте cd, чтобы найти папку Assign1.
    3. Введите jar c Assign1> Assign1.jar
    Если это не работает правильно (е.г., вы видите сообщение, `jar 'не распознается ...), см. примечание ниже.
    Что делать, если javadoc и jar не работают?
    Это связано с тем, что переменная `` путь '' вашей ОС не настроена для поиска программы javadoc и jar. Чтобы исправить это, пожалуйста, прочтите информацию на странице, Установка переменной path для использования JDK с Windows.

    Как добавлять комментарии в код с помощью Javadoc

    Одна из приятных особенностей Java - это javadoc. Утилита javadoc позволяет размещать комментарии рядом с кодом внутри файла ".java "исходные файлы. Когда вас устраивает код и комментарии, вы просто запускаете команду javadoc , и документация в стиле HTML создается для вас автоматически.

    В том, чтобы оставлять комментарии рядом с кодом, замечательно то, что намного проще синхронизировать код и документацию. Когда вы меняете код, вы меняете комментарии и снова запускаете javadoc. Очень просто, очень чисто.

    Рабочий пример

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

    Первое, на что следует обратить внимание, это то, что комментарии javadoc начинаются с символа / ** и заканчиваются символом * / . Это немного отличается от стандартных комментариев в стиле C или C ++, которые вы, возможно, привыкли видеть.

    / **
    * Porsche.java - простой класс для демонстрации использования комментариев javadoc.
    * @author Элвин Александр
    * @ версия 1.0
    * @see Автомобиль
    * /
    общественный класс Porsche расширяет Automobile {
    
       защищенный цвет строки;
    
       / **
        * Получить значение цвета.
        * @return Тип данных String.
        * /
       public String getColor () {
          вернуть цвет;
       }
    
       / **
        * Установите значение цвета.
        * @param newColor Переменная типа String.
        * /
       public void setColor (String newColor) {
          color = newColor;
       }
    }
     

    Как видно из листинга, javadoc также позволяет вам определять определенные теги в комментариях javadoc.Использование этих тегов заставляет javadoc создавать дополнительную (и лучшую) документацию от вашего имени.

    В таблице ниже кратко описывается назначение тегов javadoc, используемых в примере исходного кода, показанном выше:

    @author Этот тег позволяет вам указать имя автора кода в документации.
    @ параметр Этот тег используется для определения параметров, которые передаются в метод.
    @ возврат Этот тег определяет значения, возвращаемые методами.
    @ см. Этот тег создает вывод «См. Также:». Обычно вы используете этот тег для ссылки на связанные классы.
    @ версия Этот тег позволяет определить версию разрабатываемого кода Java. Например, код, показанный в листинге 1, считается версией 1.0.

    В этой таблице показаны наиболее часто используемые теги Javadoc.

    Как это работает

    При работе с javadoc нужно беспокоиться только о нескольких правилах. Имейте это в виду при создании документации javadoc в своем коде:

    • Комментарии Javadoc имеют смысл только тогда, когда они появляются перед открытым классом или перед общедоступными или защищенными переменными и методами.
    • Первая строка в комментарии javadoc - это итоговая строка.Вы увидите это описание в верхней части HTML-файла для класса (например, Porsche.html ), а также в файле AllNames.html .

    Также обратите внимание, что нет необходимости начинать каждую строку комментариев со звездочки, как мы показали выше. Это просто соглашение многих программистов, но не стандарт. Если вам не нравится это соглашение, просто начните комментарий с символов / ** и завершите их символами * / .

    Создание документа Javadoc

    После того, как вы создали свой код, просто запустите команду javadoc для вашего файла ".java", например:

    javadoc Porsche.java
     

    Когда вы это сделаете, javadoc генерирует документацию в формате HTML для всех ваших общедоступных классов, а также ваших общедоступных и защищенных методов и переменных. На основе отправленных вами файлов и документации в этих файлах javadoc создает четыре типа файлов HTML, как показано ниже:

    упаковок.HTML Список всех пакетов, для которых вы создали документацию, и содержащихся в них классов. В таком небольшом примере, как наш, этот файл не будет содержать действительно полезной информации.
    AllNames.html Этот файл содержит алфавитный указатель всех переменных (также называемых полями) и методов, которые вы определили.
    tree.html Список всех классов, для которых вы создали документацию, и место этих классов в иерархии классов.
    Porsche.html Для каждого определенного класса будет один файл этого типа. Этот файл содержит фактическую документацию для класса.

    В этой таблице представлены краткие описания файлов, созданных при запуске команды javadoc для исходных файлов Java.

    Выходная документация javadoc

    Ну хватит, как это работает. Лучший способ показать, как на самом деле работает javadoc, - это показать вывод, который он генерирует.

  • Добавить комментарий

    Ваш адрес email не будет опубликован. Обязательные поля помечены *