В Firebase мы использовали Doxygen для создания справочной документации по API iOS. Хотя он выполнял свою работу для ObjectiveC, он не поддерживал Swift. Мы начали использовать Jazzy для внешнего вида официальной справочной документации Apple. Документация, к которой привыкли разработчики iOS.

Jazzy - это утилита командной строки, которая генерирует документацию для Swift или Objective-C. Она состоит из двух частей:

  1. Парсер SourceKitten (написан на Swift)
  2. Генератор сайтов (написан на рубине)

Он использует

В нашей настройке у нас есть сценарий оболочки. Это

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

С первой попытки мы были поражены красивой документацией прямо из пакета. Но мы увидели пару проблем. Они возникли из-за того, что Jazzy принимал только комментарии в стиле ObjectiveC / Swift. В то время как Doxygen поддерживал комментарии в стиле C ++. Прежде чем углубиться в каждую проблему, позвольте мне объяснить, как мы их решали:

  1. Мы создали руководство по стилю Jazzy для комментариев для дальнейшего развития.
  2. Мы использовали параметр Jazzy’s--skip-documentation, чтобы найти отсутствующие или неработающие комментарии. Мы также интегрировали этот параметр в наш скрипт для проверки.
  3. Мы работали с инженерами, чтобы как можно скорее преобразовать комментарии в новый синтаксис.
  4. Тем временем мы создали сценарий предварительной обработки. Он временно удаляет неподдерживаемые ключевые слова из наших файлов заголовков (только для выполнения).
sed -i ‘’ -e ‘s/ * @method [:_.[:alnum:]]*[:[:alnum:]]//g’ *.h
sed -i ‘’ -e ‘s/ * @typedef [:_.[:alnum:]]*[:[:alnum:]]//g’ *.h
sed -i ‘’ -e ‘s/ * @class [:_.[:alnum:]]*[:[:alnum:]]//g’ *.h
sed -i ‘’ -e ‘s/ * @fn [:_.[:alnum:]]*[:[:alnum:]]//g’ *.h
sed -i ‘’ -e ‘s/ * @property [:_.[:alnum:]]*[:[:alnum:]]//g’ *.h
sed -i ‘’ -e ‘s/ * @enum [:_.[\:alnum:]]*[:[:alnum:]]//g’ *.h
sed -i ‘’ -e ‘s/@abstract //g’ *.h
sed -i ‘’ -e ‘s/@brief //g’ *.h
sed -i ‘’ -e ‘s/@discussion //g’ *.h
sed -i ‘’ -e ‘s/@remarks //g’ *.h
sed -i ‘’ -e ‘s/@returns/Returns/g’ *.h
sed -i ‘’ -e ‘s/ @memberof [:_.[:alnum:]]*[:[:alnum:]]//g’ *.h
sed -i ‘’ -e ‘s/ @related[:_.[:alnum:]]*[:[:alnum:]]//g’ *.h
sed -i ‘’ -e ‘s/{@link \([:_.[:alnum:]]*[:[:alnum:]]\)}/<code>\1<\/code>/g’ *.h
sed -i ‘’ -e ‘s/@c \([:_.[:alnum:]]*[:[:alnum:]]\)/<code>\1<\/code>/g’ *.h

Вы можете продолжать читать Руководство по миграции с Doxygen на Jazzy.