Вопрос о документации для проекта SDK

swift
ios
xcode

#1

Я делаю документацию для проекта SDK. В настоящее время я делаю это с помощью DocC.

Мой вопрос в том, что я начинающий iOS-разработчик. Я не уверен, правильно ли я делаю документацию. Когда я создаю документацию, она показывает Обзор, темы и внутри тем есть разделы, такие как Bluetooth, основные расширения bluetooth и т.д. Я просто пишу коды и пояснения к ним:

Пример:

/// Возможные состояния менеджера Core Bluetooth.
public enum CBManagerState: Int, Sendable {

/// Состояние, указывающее на то, что Bluetooth в данный момент выключен.
case poweredOff = 4

/// Состояние, указывающее на то, что Bluetooth включен и доступен для использования.
case poweredOn = 5

/// Состояние, указывающее на то, что соединение с системной службой было временно потеряно.
///
/// Это состояние указывает на то, что Bluetooth пытается восстановить соединение. После восстановления соединения Core Bluetooth обновляет значение состояния.
case resetting = 1

/// Состояние, указывающее на то, что приложение не авторизовано для использования роли Bluetooth low energy.
case unauthorized = 3

/// Состояние менеджера неизвестно.
///
/// Это временное состояние. После инициализации или сброса Core Bluetooth обновляет значение состояния.
case unknown = 0

/// Состояние, указывающее на то, что это устройство не поддерживает роль центрального или клиентского Bluetooth low energy.
case unsupported = 2

}

Это правильная документация для проекта SDK? Или мне просто открыть word и написать там функции и пояснения к ним, например:

Methods:

  • scanForDevice(timeout: “”)
  • Запускает сканирование bluetooth с фильтром сканирования и настройками сканирования, созданными атрибутами этого класса.
  • Сканирование Bluetooth отменяется по достижении заданного таймаута.
  • Приложения должны использовать эту функцию только в тех случаях, когда не требуется автоматическое подключение и авторизация в функции connect().

Если вы можете помочь мне, я буду благодарен, потому что я потерялся в этой теме.

Кстати, это мой первый раз, когда я делаю документацию для проекта SDK.


#2

Вас все мучают с этой документацией… Это какой-то фетиш местный у компании где вы работаете.
Я лично не встречал такой темы в разных ЯП как написание документации. Этому не учат в области ЯП.
Тут либо идет подрожание стилю(если вам показывали примеры документаций, которые делают в компании), либо на свое понимание, но для этого нужно знать и разбираться в тонкостях проекта.
Вам остается либо попросить у компании пример, либо найти в гитхабе популярную СДК и посмотреть как сделана документация там.

Если не секрет, можно узнать название компании?


#3

Я работаю в Германии. Компания Daimler (Mercedes).

Они поделились со мной документацией для iOS, но она еще не готова, я должен ее завершить. В то же время они поделились со мной (в формате PDF) документацией для Android, которая уже готова.

Но дело в том, что сейчас я делаю документацию с помощью DocC. Ранее другие ребята делали (что еще не завершено) с помощью JayzZ. Я делаю так, как я понял, но не уверен, правильно ли я понимаю. Я спрашивал у других членов команды, они сказали, что у них нет идей, потому что они этого не делали.

Если у вас есть, не могли бы вы поделиться со мной ссылкой на документацию SDK с github? Я ищу, но ничего не могу найти.

Кроме того, знаете ли вы, как экспортировать всю эту документацию в PDF после того, как она будет закончена в DocC? Или это невозможно?


#4

Посмотрите это


Но это компилер для готовой документации как я понял и вроде в формат DocC.

А популярные SDK можете глянуть тут

P.S. у вас случаем нету документации к расшифровке кодовых ошибок для машин? может проект какой на swift или android?