Обектив C @property коментари

Използвам Doxygen за генериране на документи за моя objective c код. Досега обаче не успях да намеря никакви насоки за това как правилно да документирам свойствата. Примерите, които разгледах, го правят по всеки възможен начин. Някои хора документират самите променливи, други документират декларациите на @property. Някои използват //, докато други използват пълни /** */ блокове.

Може ли някой да ме насочи към справка за най-добри практики? Или може би някаква информация за бъдеща съвместимост с Doxygen? Бих искал да се придържам към модел, който най-малкото ще бъде лесен за адаптиране към Doxygen, след като разработят официален модел.


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

Отговори (3)


arrow_upward
11
arrow_downward

Всичко, което мога да кажа, е, че рамката Core Plot анотира декларациите за свойства в изпълнението с помощта на формат като

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

и изглежда, че създава чиста документация с помощта на Doxygen. От Правилата за документиране на Core Plot:

@property се изисква, тъй като doxygen не може да намери името на свойството по друг начин.

Свойствата на Accessor като само за четене, копиране/запазване/присвояване и неатомични се добавят автоматично и не трябва да се появяват в ръчната част на документацията.

person Brad Larson    schedule 05.03.2010

arrow_upward
4
arrow_downward

Тук можете да намерите малко информация относно конвенцията за кодиране за Objective-C: Google Objective -C Ръководство за стил

Но ако искате, има друга добра програма, наречена HeaderDoc, за генериране на документация под XCode. Можете да проверите неговия стил на кодиране тук: Етикети на HeaderDoc

person Yannick Loriot    schedule 04.03.2010
comment
Полезни препратки и гласувах за това, но всъщност не отговаря на нито един от въпросите ми. Документът на Google пропуска всякакви насоки за коментиране на @property, а headerdoc със сигурност е алтернатива, но не и решение за мен. - person DougW; 06.03.2010

arrow_upward
1
arrow_downward

Моят опит е:

Когато използвам маркера @property вътре в коментарите, изходът на doxygen на свойствата се поврежда като: [Име на клас]:[четене, писане, присвояване].

Ако пропусна маркера @property и вместо това разчитам на doxygen да намери декларацията „@property“ в изходния код, точно под блока за коментари, всичко работи добре.

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

Също така, в миналото имах doxygen 'slip' на някои декларации на протоколи. Obj-C все още ли е второкласен доксиген гражданин?

Забележка: Използвам GUI/Wizard на Mac и блоковете за коментари използват '/**!' вместо '/**'.

person Nicolas Miari    schedule 24.08.2011