Suppress kotlin что это
Типы сообщений компилятора Kotlin, которые нужно использовать в Suppress
Предупреждения и ошибки, которые генерирует компилятор Kotlin часто нужно замаскировать, либо для того, чтобы они не мозолили глаза, либо просто потому, что логика программы нуждается именно в таком коде, который приводит к сообщению об ошибке или предупреждению.
Маскировка сообщений компилятора как в Java так и Kotlin происходит одинаково:
где «MESSAGE» — это тип сообщения.
Проблема в том, что узнать каким-то простым способом какой тип сообщения соответствует конкретному тексту часто оказывается невозможно. Подсказки Lint работают почему-то сильно не всегда, автодополнения нет, а разработчиками Kotlin эта информация почему-то нигде не опубликована.
Для облегчения поиска нужных типов сообщений я свел их вместе с текстом в одну таблицу. В случае возникновения необходимости замаскировать какое-то сообщение его можно легко найти в этой таблице и узнать какой тип нужно указать для ее подавления.
Пример таблицы
| Тип | Сообщение |
|---|---|
| Data class inheritance from other classes is forbidden | DATA_CLASS_CANNOT_HAVE_CLASS_SUPERTYPES |
| Data class must have at least one primary constructor parameter | DATA_CLASS_WITHOUT_PARAMETERS |
В один поста на хабре таблицу сообщений засунуть невозможно, а размазывать ее по нескольким сообщением не имеет смысла т.к. ею будет неудобно пользоваться, поэтому я выложил ее на GitHub.
Возможно, кому-то эта информация пригодится.
Типы сообщений компилятора Kotlin, которые нужно использовать в Suppress
Предупреждения и ошибки, которые генерирует компилятор Kotlin часто нужно замаскировать, либо для того, чтобы они не мозолили глаза, либо просто потому, что логика программы нуждается именно в таком коде, который приводит к сообщению об ошибке или предупреждению.
Маскировка сообщений компилятора как в Java так и Kotlin происходит одинаково:
где «MESSAGE» — это тип сообщения.
Проблема в том, что узнать каким-то простым способом какой тип сообщения соответствует конкретному тексту часто оказывается невозможно. Подсказки Lint работают почему-то сильно не всегда, автодополнения нет, а разработчиками Kotlin эта информация почему-то нигде не опубликована.
Для облегчения поиска нужных типов сообщений я свел их вместе с текстом в одну таблицу. В случае возникновения необходимости замаскировать какое-то сообщение его можно легко найти в этой таблице и узнать какой тип нужно указать для ее подавления.
Пример таблицы
| Тип | Сообщение |
|---|---|
| Data class inheritance from other classes is forbidden | DATA_CLASS_CANNOT_HAVE_CLASS_SUPERTYPES |
| Data class must have at least one primary constructor parameter | DATA_CLASS_WITHOUT_PARAMETERS |
В один поста на хабре таблицу сообщений засунуть невозможно, а размазывать ее по нескольким сообщением не имеет смысла т.к. ею будет неудобно пользоваться, поэтому я выложил ее на GitHub.
Возможно, кому-то эта информация пригодится.
Типы сообщений компилятора Kotlin, которые нужно использовать в Suppress
Предупреждения и ошибки, которые генерирует компилятор Kotlin часто нужно замаскировать, либо для того, чтобы они не мозолили глаза, либо просто потому, что логика программы нуждается именно в таком коде, который приводит к сообщению об ошибке или предупреждению.
Маскировка сообщений компилятора как в Java так и Kotlin происходит одинаково:
где «MESSAGE» — это тип сообщения.
Проблема в том, что узнать каким-то простым способом какой тип сообщения соответствует конкретному тексту часто оказывается невозможно. Подсказки Lint работают почему-то сильно не всегда, автодополнения нет, а разработчиками Kotlin эта информация почему-то нигде не опубликована.
Для облегчения поиска нужных типов сообщений я свел их вместе с текстом в одну таблицу. В случае возникновения необходимости замаскировать какое-то сообщение его можно легко найти в этой таблице и узнать какой тип нужно указать для ее подавления.
Пример таблицы
| Тип | Сообщение |
|---|---|
| Data class inheritance from other classes is forbidden | DATA_CLASS_CANNOT_HAVE_CLASS_SUPERTYPES |
| Data class must have at least one primary constructor parameter | DATA_CLASS_WITHOUT_PARAMETERS |
В один поста на хабре таблицу сообщений засунуть невозможно, а размазывать ее по нескольким сообщением не имеет смысла т.к. ею будет неудобно пользоваться, поэтому я выложил ее на GitHub.
Возможно, кому-то эта информация пригодится.
Документация Kotlin кода
Язык для документации Kotlin кода (являющийся аналогом Java JavaDoc) называется KDoc. По сути, KDoc комбинирует JavaDoc синтаксис для тегов (расширенных для поддержки специфичных Kotlin конструкций) и Markdown для встроенной разметки.
Генерация документации
Утилита для генерации Kotlin документации называется Dokka. Смотрите инструкцию по использованию Dokka README.
В Dokka есть плагины для Gradle, Maven и Ant, поэтому вы можете интегрировать создание документации в свой процесс сборки.
KDoc синтаксис
Ниже пример документации класса с использованием KDoc:
KDoc поддерживает следующие теги:
@param
Описание аргументов функции или типов параметров класса, свойств или функций. Для более удобного разделения названия параметра и его описания, при необходимости, можно заключать имя параметра в квадратные скобки. Два приведенных ниже синтаксиса равнозначны:
@return
Описание возвращаемого функцией значения.
@constructor
Описание первичного конструктора класса.
@receiver
Описание расширения функции.
@property
Описание свойства класса, имеющего указанное имя. Этот тег может использоваться для документации свойств указанных в основном кострукторе, где описание свойств прямо до их объявления выглядит нелепо.
Описание исключений которые может отправить класс. Поскольку Kotlin не имеет проверенных исключений, не ожидается, что все возможные исключения будут задокументированы, но вы можете использовать этот тег, когда он дает полезную информацию по работе класса.
@sample
Добавляется в тело функции с указанным именем элемента, чтобы показать пример того, как этот элемент можно использовать.
Добавляет ссылку на спецификацию класса или метода на See Also блок документации.
@author
Определяет автора документируемого элемента.
@since
Указывает версию программного обеспечения, в которой элемент был документирован.
@suppress
Исключает элемент из генерируемой документации. Может использоваться для элементов, которые не являются частью официального API, но до сих пор должны быть доступны.
KDoc не поддерживает @deprecated тег. Вместо него используйте @Deprecated аннотацию.
Встроенная разметка
Для встроенной разметки KDoc использует Markdown синтаксис, расширенный для поддержки сокращенного синтаксиса с возможностью привязки к другим элементам кода.
Привязка элементов
Для связи с элементом (классом, методом, свойством или параметром), достаточно указать его имя в квадратных скобках:
Если вы хотите ввести свое обозначение для ссылки, используйте следующий Markdown синтаксис:
Вы также можете использовать подходящее имя в ссылках. Заметьте, в отличие от JavaDoc, подходящее имя всегда использует точку для разделения компонентов, даже до имени метода:
На имена в ссылках действуют такие же правила, как и на имена использованные внутри документации. В частности, это означает, что если вы импортировали имя в текущий файл, вам не нужно полностью определять его, когда вы используете его в комментариях KDoc.
Заметьте, что KDoc не имеет синтаксиса для обозначения переопределенных функций. Поскольку Kotlin инструмент генерации документации добавляет все переопределенные методы в один файл, особое обозначение переопределенных функций не требуется для корректной работы ссылок.
Документирование модулей и пакетов
Внутри файла, документация для заголовка модуля и отдельных пакетов обозначается заголовком первого уровня. Текст заголовка должен содержать «Module » для модуля, и «Package
Ниже приведены примеры документации модулей и пакетов:
Документация Kotlin кода
Язык для документации Kotlin кода (являющийся аналогом Java JavaDoc) называется KDoc. По сути, KDoc комбинирует JavaDoc синтаксис для тегов (расширенных для поддержки специфичных Kotlin конструкций) и Markdown для встроенной разметки.
Генерация документации
Утилита для генерации Kotlin документации называется Dokka. Смотрите инструкцию по использованию Dokka README.
В Dokka есть плагины для Gradle, Maven и Ant, поэтому вы можете интегрировать создание документации в свой процесс сборки.
KDoc синтаксис
Ниже пример документации класса с использованием KDoc:
KDoc поддерживает следующие теги:
@param
Описание аргументов функции или типов параметров класса, свойств или функций. Для более удобного разделения названия параметра и его описания, при необходимости, можно заключать имя параметра в квадратные скобки. Два приведенных ниже синтаксиса равнозначны:
@return
Описание возвращаемого функцией значения.
@constructor
Описание первичного конструктора класса.
@receiver
Описание расширения функции.
@property
Описание свойства класса, имеющего указанное имя. Этот тег может использоваться для документации свойств указанных в основном кострукторе, где описание свойств прямо до их объявления выглядит нелепо.
Описание исключений которые может отправить класс. Поскольку Kotlin не имеет проверенных исключений, не ожидается, что все возможные исключения будут задокументированы, но вы можете использовать этот тег, когда он дает полезную информацию по работе класса.
@sample
Добавляется в тело функции с указанным именем элемента, чтобы показать пример того, как этот элемент можно использовать.
Добавляет ссылку на спецификацию класса или метода на See Also блок документации.
@author
Определяет автора документируемого элемента.
@since
Указывает версию программного обеспечения, в которой элемент был документирован.
@suppress
Исключает элемент из генерируемой документации. Может использоваться для элементов, которые не являются частью официального API, но до сих пор должны быть доступны.
KDoc не поддерживает @deprecated тег. Вместо него используйте @Deprecated аннотацию.
Встроенная разметка
Для встроенной разметки KDoc использует Markdown синтаксис, расширенный для поддержки сокращенного синтаксиса с возможностью привязки к другим элементам кода.
Привязка элементов
Для связи с элементом (классом, методом, свойством или параметром), достаточно указать его имя в квадратных скобках:
Если вы хотите ввести свое обозначение для ссылки, используйте следующий Markdown синтаксис:
Вы также можете использовать подходящее имя в ссылках. Заметьте, в отличие от JavaDoc, подходящее имя всегда использует точку для разделения компонентов, даже до имени метода:
На имена в ссылках действуют такие же правила, как и на имена использованные внутри документации. В частности, это означает, что если вы импортировали имя в текущий файл, вам не нужно полностью определять его, когда вы используете его в комментариях KDoc.
Заметьте, что KDoc не имеет синтаксиса для обозначения переопределенных функций. Поскольку Kotlin инструмент генерации документации добавляет все переопределенные методы в один файл, особое обозначение переопределенных функций не требуется для корректной работы ссылок.
Документирование модулей и пакетов
Внутри файла, документация для заголовка модуля и отдельных пакетов обозначается заголовком первого уровня. Текст заголовка должен содержать «Module » для модуля, и «Package
Ниже приведены примеры документации модулей и пакетов: