Objective C @property комментарии

Question

Я использую Doxygen для генерации документов для моего целевого кода c. До сих пор, однако, я не смог найти какие-либо рекомендации о том, как правильно задокументировать свойства. Примеры, на которые я смотрел, делают это всевозможными способами. Некоторые люди документируют переменные сами, некоторые документируют объявления @property. Некоторые используют //, в то время как другие используют полные / ** * / блоки.

Может кто-нибудь указать мне ссылку на лучшие практики? Или, может быть, какая-то информация о будущей совместимости с Doxygen? Я хотел бы придерживаться схемы, которую, по крайней мере, будет легко адаптировать к Doxygen, когда они разработают официальный шаблон.

Answer 1

Все, что я могу сказать, это то, что Core Plot Framework аннотирует объявления свойств в реализации с использованием формата, подобного

 /** @property myProperty
 *   @brief Property is very useful
 *   Useful and there is a lot more to tell about this property **/

, и, похоже, создает чистую документацию с использованием Doxygen.Из политики документации Core Plot :

@property требуется, так как в противном случае doxygen не может найти имя свойства.

Свойства средства доступа, такие как readonly, копировать / сохранить/ assign и nonatomic добавляются автоматически и не должны встречаться в ручной части документации.

Answer 2

Здесь вы можете найти некоторую информацию о соглашении по кодированию для Objective-C: Руководство по стилю Google Objective-C

Но если хотите, есть другой хороший софт под названием HeaderDoc для генерации документации под XCode. Вы можете проверить его стиль кодирования здесь: Теги HeaderDoc

Answer 3

Мой опыт:

Когда я использую тег @property внутри комментариев, выходные данные свойств doxygen искажаются, например: [ClassName]: [read, write, assign].

Если я пропускаю тег @property и вместо этого полагаюсь на то, что doxygen находит объявление '@property' в исходном коде, прямо под блоком комментариев, все работает нормально.

Напротив, @interface отлично работает для интерфейсов, а @protocol отлично работает для протоколов.

Кроме того, в прошлом у меня было «проскальзывание» doxygen в некоторых протоколах. Является ли Obj-C гражданином-кислородом второго сорта?

Примечание: я использую GUI / Wizard на Mac, а блоки комментариев используют '/ **!' вместо '/**'.