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

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

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

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

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

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

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

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

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

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

У меня возникли проблемы с шаблонами файлов для разработки 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 description.
@param[name] description.

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

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

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

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

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

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

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

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

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

Исключает элемент из генерируемой документации. Может использоваться для элементов, которые не являются частью официального 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.

*

*

*

*

*

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

* идентификатора в перечислении 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 Установка

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

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

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

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

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

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

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

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

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

/ **
 * Это Javadoc
 * /  

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Методы могут содержать множество тегов блоков 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 мог сгенерировать что-нибудь значимое.

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

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

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

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

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

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

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

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

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

Мы также можем использовать плагин 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 . Мы можем видеть наше описание, поля и метод, а также можем щелкать ссылки для получения дополнительной информации.

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

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

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

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

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

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

...  

/ **
 * Представляет ученика, зачисленного в школу.
 * Студент может быть зачислен на многие курсы.
 * /
public class Student {

  / **
   * Имя и фамилия этого студента.
   * /
  частное строковое имя;

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

}
 

  / **
   * Получает имя и фамилию этого ученика.
   * @ вернуть имя этого студента.
   * /
  public String getName () {
    возвращаемое имя;
  }

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

  java.applet
  java.awt
  java.awt.color
  и т.п.
 

javadoc -ссылка http: // java.sun.com/products/jdk/1.2/docs/api
 

 javadoc -d html -link html mypackage
 

/ **
* 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 Porsche.java