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

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

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


iphone objective-c comments doxygen
person DougW    schedule 04.03.2010    source источник

Ответы (3)


arrow_upward
11
arrow_downward

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

 /** @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, copy/retain/assign и неатомарные, добавляются автоматически и не должны встречаться в ручной части документации.

person Brad Larson    schedule 05.03.2010

arrow_upward
4
arrow_downward

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

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

person Yannick Loriot    schedule 04.03.2010
comment
Полезные ссылки, и я проголосовал за это, но на самом деле не отвечает ни на один из моих вопросов. Документ Google опускает какие-либо рекомендации по комментированию @property, и headerdoc, безусловно, является альтернативой, но не решением для меня. - person DougW; 06.03.2010

arrow_upward
1
arrow_downward

Мой опыт:

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

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

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

Кроме того, в прошлом у меня были ошибки doxygen в некоторых декларациях протокола. Obj-C все еще второсортный гражданин Doxygen?

Примечание. Я использую графический интерфейс/мастер на Mac, а блоки комментариев используют '/**!' вместо '/**'.

person Nicolas Miari    schedule 24.08.2011