Разработчик, который открывает Android Studio впервые, почти сразу сталкивается с вопросом: где искать описание классов, методов и настроек IDE, когда подсказка по Ctrl+Q показывает «No documentation found». Эта ситуация обычно означает, что не скачаны пакеты документации через SDK Manager либо среда не может связать символ с источником. Разобраться с документацией Android Studio нужно на двух уровнях: официальные справочные материалы от Google и встроенные механизмы просмотра справки прямо в редакторе кода.
В этой статье разберём, где находится официальная документация, как настроить быстрый доступ к ней из среды разработки, как оформлять собственные комментарии в стиле KDoc и Javadoc, и какие инструменты помогают генерировать документацию по проекту автоматически.
Где находится официальная документация Android Studio
Основной источник информации — официальный сайт для разработчиков developer.android.com. Именно там Google публикует руководства по IDE, описания API платформы Android, рекомендации по архитектуре приложений и заметки о релизах. Раздел Android Studio User Guide охватывает настройку среды, работу с эмулятором, профилировщик и систему сборки Gradle.
Документация делится на несколько логических блоков. Справочник API Reference описывает каждый класс и метод Android SDK с указанием уровня API, в котором они появились. Гайды (Guides) объясняют концепции — от жизненного цикла Activity до работы с Jetpack-библиотеками. Раздел Samples содержит готовые примеры кода, которые можно импортировать прямо в IDE через мастер создания проекта.
- 📘 API Reference — полное описание классов, методов и констант платформы
- 🛠️ User Guide — инструкции по настройке и использованию Android Studio
- 📦 Samples — примеры проектов, доступные через
File → New → Import Sample - 📝 Release Notes — изменения в каждой версии IDE и плагина Android Gradle
⚠️ Внимание: сторонние сайты и переведённые копии документации часто отстают от актуальных версий. Сверяйте описание API с официальным источником, особенно если метод помечен как устаревший (deprecated) — поведение могло измениться в новых уровнях API.
Встроенная справка и быстрый просмотр документации в IDE
Android Studio умеет показывать документацию без перехода в браузер. Поставьте курсор на любой класс или метод и нажмите Ctrl+Q (на macOS — F1): появится всплывающее окно с описанием, сигнатурой и ссылками на связанные элементы. Если вместо текста отображается заглушка, среде не хватает локальных источников документации.
Проверьте, скачан ли пакет Documentation for Android SDK. Откройте File → Settings → Appearance & Behavior → System Settings → Android SDK, перейдите на вкладку SDK Tools и убедитесь, что соответствующий компонент установлен. После установки быстрый просмотр начнёт подтягивать описания офлайн.
☑️ Настройка документации в Android Studio
Для открытия полной страницы документации в браузере используется комбинация Shift+F1 — IDE передаст в поисковый запрос имя символа под курсором. Это удобно, когда краткой всплывающей подсказки недостаточно и нужны примеры использования.
Документирование собственного кода: KDoc и Javadoc
Для проектов на Kotlin стандартом является KDoc — формат комментариев, похожий на Javadoc, но использующий синтаксис Markdown. Для Java-кода применяется классический Javadoc. Оба формата распознаются Android Studio: написанные вами комментарии отображаются в том же всплывающем окне Ctrl+Q, что и документация платформы.
Блок документации начинается с /** и размещается непосредственно перед объявлением класса, функции или свойства. Внутри используются теги для структурирования описания.
/**
* Вычисляет итоговую стоимость заказа с учётом скидки.
*
* @param items список позиций заказа
* @param discountPercent размер скидки в процентах
* @return итоговая сумма после применения скидки
*/
fun calculateTotal(items: List<Item>, discountPercent: Int): Double
- 🏷️
@param— описание параметра функции - ↩️
@return— что возвращает функция - ⚡
@throws— какие исключения может выбросить метод - 🔗
@see— ссылка на связанный класс или метод - 🗑️
@deprecated— пометка об устаревшем API с указанием замены
Чтобы быстро сгенерировать заготовку комментария, введите /** перед объявлением и нажмите Enter — IDE автоматически создаст шаблон с тегами для всех параметров и возвращаемого значения.
Генерация документации по проекту
Когда проект разрастается, возникает потребность собрать всю документацию в виде отдельного сайта или HTML-архива. Для Java-кода это делает стандартная утилита javadoc, для Kotlin — инструмент Dokka от JetBrains, который понимает и KDoc, и Javadoc-комментарии в смешанных проектах.
Dokka подключается как Gradle-плагин. После добавления плагина в файл сборки появляются задачи генерации документации, результат которой складывается в каталог сборки проекта. Точные координаты плагина и имена задач зависят от версии, поэтому сверяйтесь с официальной документацией Dokka перед настройкой.
plugins {
id("org.jetbrains.dokka") version "..."
}
Документация, сгенерированная из KDoc-комментариев, остаётся актуальной ровно настолько, насколько дисциплинированно команда обновляет комментарии при изменении кода — автоматизация решает проблему формата, но не содержания.
Что делать, если Ctrl+Q показывает «No documentation found»
Проверьте три вещи. Во-первых, установлен ли пакет Documentation for Android SDK в SDK Manager. Во-вторых, скачаны ли Sources for Android SDK — без исходников IDE не всегда может связать символ с описанием. В-третьих, для сторонних библиотек документация доступна, только если опубликована вместе с артефактом (sources/javadoc jar); для многих библиотек быстрый просмотр покажет только сигнатуру.
Полезные разделы документации для повседневной работы
Не все разделы официальной документации одинаково востребованы. На практике чаще всего приходится обращаться к ограниченному набору материалов, которые стоит держать под рукой.
| Раздел | Что содержит | Когда нужен |
|---|---|---|
| API Reference | Описание классов и методов SDK | Ежедневно при написании кода |
| Build configuration | Настройка Gradle, build variants | При настройке сборки и flavors |
| Release Notes | Изменения в версиях IDE и AGP | Перед обновлением инструментов |
| Behavior changes | Изменения поведения платформы | При повышении targetSdkVersion |
| Jetpack libraries | Документация библиотек AndroidX | При подключении новых зависимостей |
⚠️ Внимание: перед обновлением Android Studio или Android Gradle Plugin обязательно читайте заметки о релизе. Изменения в системе сборки могут потребовать правок в файлах build.gradle, а несовместимые версии IDE и плагина приводят к ошибкам синхронизации проекта.
Типичные проблемы и их решения
Даже при корректной настройке работа с документацией в Android Studio иногда даёт сбои. Разберём самые частые сценарии.
Не отображается документация для классов SDK. Проверьте SDK Manager: пакеты документации и исходников устанавливаются отдельно для каждой версии платформы. Если проект собирается под новый уровень API, а документация скачана только для старого, быстрый просмотр будет пустым.
Документация сторонней библиотеки недоступна. Это нормально: всплывающая подсказка работает только для артефактов, опубликованных с прилагаемыми sources или javadoc. Выход — открыть исходный код библиотеки на GitHub или её официальный сайт. Возможная альтернатива — просмотр декомпилированного кода через двойной клик по классу с зажатым Ctrl.
KDoc-комментарии не отображаются в подсказке. Убедитесь, что комментарий начинается именно с /** (две звёздочки), а не с обычного /*, и стоит непосредственно перед объявлением без пустых строк между ними.
⚠️ Внимание: после обновления IDE индексы могут перестраиваться, и быстрая документация временно работает медленно или неполно. Дождитесь завершения индексации (индикатор в нижней части окна) перед тем, как считать проблему неисправностью.
Часто задаваемые вопросы
Где скачать официальную документацию Android Studio для офлайн-доступа?
Локальная документация по SDK устанавливается через SDK Manager (пакет Documentation for Android SDK). Полный офлайн-архив всего сайта developer.android.com официально не распространяется — для глубокой работы без интернета используйте локальные пакеты и встроенный просмотр Ctrl+Q.
Чем KDoc отличается от Javadoc?
KDoc — стандарт документирования для Kotlin, использующий разметку Markdown внутри комментариев. Javadoc — классический формат для Java с HTML-разметкой. Android Studio понимает оба, а инструмент Dokka генерирует документацию из обоих форматов в смешанных проектах.
Почему Ctrl+Q показывает «No documentation found»?
Чаще всего не установлен пакет Documentation for Android SDK или Sources для нужной версии платформы. Проверьте SDK Manager. Для сторонних библиотек причина может быть в том, что артефакт опубликован без прилагаемой документации.
Как автоматически создать шаблон документирующего комментария?
Введите /** на строке перед объявлением функции или класса и нажмите Enter — Android Studio сгенерирует заготовку с тегами для всех параметров и возвращаемого значения.
Нужно ли документировать каждый метод в проекте?
Нет. Разумный подход — документировать публичный API модулей, неочевидную логику и причины принятых решений. Самодокументирующийся код с понятными именами часто не нуждается в комментариях, а избыточное описание очевидных вещей быстро устаревает и вводит в заблуждение.