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

План• Источники API документации

• Обзор систем для создания API документации

• Выберем систему

• Процесс создания документации

• Процесс создания гайдов

Источники API документации

• Исходный код, публичный интерфейс

• Quick Help

• Xcode Documentation

• Внешние источники

Внешние источники• Не нужно скачивать исходный код

• Не нужно искать исходный код на репозитории проекта

• Вся документация в одном месте

• Можно ссылаться на документацию при описании гайдов (html)

Способы создания API документации

• headerdoc

• appledoc

• jazzy

Способы создания API документации

Удобство работы

Поддержка objective-c

Поддержка swift

Активно поддержива

ется Красивая

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

шаблоны

Документация генерируется сразу для

двух языков

headerdoc - + - - - - -

appledoc + + - - + + -

jazzy ++

(есть проблемы)

+ + + + +

headerdoc

headerdoc

appledoc

appledoc

jazzy

jazzy (+)• Поддержка swift/objective-c

• Документация генерируется для двух языков

• Поддержка dash

• Документация похожа на apple

• Есть ссылки на исходники метода в github/gitlab

• Активно развивается, разрабатывают realm

• Оптимизирован для генерации документации под SDK. Умеет генерировать документацию только для публичных классов

jazzy (-)

• Для objective-с генерирует документацию по umbrella header

• Не умеет находить файлы objective-c в поддиректориях

• В редких случаях не генерирует доки для swift

Dash

• Программа для просмотра и навигации по документации

• Библиотека содежит 150+ API

• Поддержка macOS и iOS

Dash

Как мы работаем с jazzy?

fastlane - create_docsEnvironment

• SOURCE_DIR - Папка исходного кода

• SOURCE_URL - Адрес репозитория

• MODULE_NAME - Отображаемое имя SDK

• UMBRELLA_HEADER - Umbrella header SDK

fastlane - create_docs

Параметры

• branch - Ветка

• version - Отображаемая версия

fastlanecreate_docs

create_develop_docsНастроен для сборки из

develop рабочей документации.

create_release_docsСобирает документацию для релизной версии. Является

одним из этапа деплоя релиза.

Создание гайдов

Confluence + API доки (как нужно)

1. Сделали много фич

2. Создали релиз ветку

3. Исправили баги

4. Написали документацию

5. Релиз

Confluence +  API доки (как получается)

1. Сделали фичу

2. Слили в develop

3. Написали документацию, ссылаясь на develop версию

4. Время релиза

5. Исправили ссылки в confluence на релизную версию

6. Исправили несоответствия документации

7. Релиз

Confluence

Confluence

Какие планы по развитию?

• pull request залить lane на наш репозиторий

• diff версий

• Автоматически заменять ссылки в confluence из develop версии на конкретный релиз

Где посмотреть

• https://appdistribution.rambler.ru/doc/index.html

Конец