Документирование с помощью комментариев dartdoc
Пишите документацию, отображаемую на pub.dev
«Документирование с помощью комментариев dartdoc» — бесплатный урок Dart Academy на CoddyKit. Это урок 2 из 4. Ты можешь прочитать весь урок бесплатно ниже — а потом практиковать его прямо в браузере с встроенным редактором кода и ИИ-репетитором 24/7. Это часть пути обучения Dart Academy, и твой прогресс синхронизируется между веб-версией и приложением CoddyKit. Курс Dart Academy содержит 4 уроков всего.
Документация — часть продукта
Отличные пакеты сопровождаются отличной документацией. Dart превращает специальные комментарии в удобный справочник, поэтому документация — полноценная возможность, а не второстепенная задача. 📝
Комментарии документации с тремя косыми чертами
Комментарий документации начинается с трёх косых черт. Эти комментарии документации располагаются непосредственно над объявлением и описывают для пользователей его назначение.
/// Adds two numbers and returns the sum.
int add(int a, int b) => a + b;Начинайте с одной строки краткого описания
Начинайте каждый комментарий документации с одного короткого предложения-резюме. Инструменты показывают эту первую строку в списках, поэтому она должна быть ясной и законченной сама по себе.
Поддержка Markdown
Комментарии документации поддерживают Markdown, поэтому в них можно добавлять выделение, списки и ссылки. Страница на pub.dev выглядит профессионально почти без дополнительных усилий.
/// Returns the **first** matching item.Ссылки на другие символы
Заключите имя в квадратные скобки, чтобы создать рабочую перекрёстную ссылку. Читатели смогут сразу перейти к связанным классам или методам в сгенерированной документации.
/// See [add] for the inverse of [subtract].Примеры кода в блоках с ограничителями
Показывайте реальное использование внутри блока кода с ограничителями в комментарии. Короткий пример обучает быстрее, чем несколько абзацев, и убеждает пользователей, что всё работает.
Документируйте каждый общедоступный элемент
Старайтесь документировать каждый общедоступный класс, функцию и поле. Приватные элементы с подчёркиванием можно не описывать, но любой экспорт заслуживает отдельного предложения.
Документация на уровне библиотеки
Поместите комментарий документации над директивой библиотеки, чтобы описать весь файл. Этот комментарий библиотеки становится вступительным текстом для соответствующей части вашего API.
/// Math helpers for everyday use.
library calc;Генерация сайта с помощью dartdoc
Запустите инструмент dartdoc, чтобы превратить комментарии в статический веб-сайт. При публикации pub.dev автоматически запускает его за вас.
dart doc .Покрытие документацией приносит баллы
pub.dev поощряет пакеты с хорошей документацией. Более высокое покрытие документацией повышает вашу оценку и демонстрирует качество тем, кто выбирает зависимость. ⭐
Держите документацию рядом с кодом
Поскольку комментарии документации находятся рядом с кодом, их легко обновлять одновременно с ним. Считайте устаревшую документацию ошибкой и исправляйте её при изменении поведения.
Быстрая проверка
Какой стиль комментариев Dart считает комментарием документации?
Итоги: документация, которая отображается
Теперь вы умеете писать комментарии документации с тремя косыми чертами, связывать символы, добавлять примеры и создавать сайт с помощью dartdoc. Понятная документация привлекает пользователей. 🙌
Часто задаваемые вопросы
Урок «Документирование с помощью комментариев dartdoc» бесплатный?
Да — полный текст урока «Документирование с помощью комментариев dartdoc» бесплатно доступен здесь в веб-версии. Чтобы практиковать его интерактивно (встроенный редактор кода и ИИ-репетитор 24/7) и разблокировать остальной курс Dart Academy, подпишись на CoddyKit PRO. Курс Dart Academy содержит 4 уроков всего.
Чему я научусь в уроке «Документирование с помощью комментариев dartdoc»?
Пишите документацию, отображаемую на pub.dev Ты практикуешь Dart Academy с помощью реального кода, который запускаешь прямо в браузере, и ИИ-репетитор 24/7 отвечает на твои вопросы во время урока.
Нужен ли мне опыт, чтобы начать Dart Academy?
Предыдущий опыт не требуется. Dart Academy на CoddyKit структурирован для всех уровней — от новичков до продвинутых, поэтому ты можешь начать отсюда или с самого начала и учиться в своем темпе. Это урок 2 из 4.
Сколько времени занимает урок «Документирование с помощью комментариев dartdoc»?
Большинство уроков CoddyKit занимают около 5–10 минут. Каждый из них компактный и интерактивный, поэтому ты постоянно делаешь прогресс и продолжаешь с того же места в веб-версии и приложении.
Можно ли писать и запускать код в этом уроке Dart Academy?
Да. Каждый урок Dart Academy включает встроенный редактор кода, поэтому ты пишешь и запускаешь реальный код прямо в браузере и получаешь моментальную обратную связь от AI — локальная установка не требуется.
Все уроки этого курса
- Структура библиотеки для публикации
- Документирование с помощью комментариев dartdoc
- Линтинг, форматирование и оценка pana
- dart pub publish для pub.dev