Документация по коду XCode

Question

Существуют ли какие-либо руководящие принципы / стандарты о том, как документировать код, написанный на XCode? Я имею в виду, есть ли способ документировать код, если вы хотите сделать его легко понятным для других? Предоставляет ли XCode инструмент, который можно использовать для автоматического создания документации, например справочных документов по API, из вашего кода + комментарии?

По крайней мере, мне интересно понять, существует ли стандартный способ написания комментариев перед интерфейсами / протоколами / методами, определенными в вашем коде. Я видел использование директив, подобных следующей, но я не понял, как они работают:

#pragma mark -
#pragma mark Initialization

Answer 1

Вы можете объединить эти две строки в одну: #pragma mark - Initialization.Нажмите на список методов (вверх, вправо), и вы увидите жирный заголовок со строкой.Это просто маркер для группировки методов в разделах.

Ссылка на руководство по кодированию, опубликованная Дереком выше, является обязательной для прочтения.

Если вы хотите создать документацию, подобную Apple, вам нужно использовать этот превосходныйи бесплатный сторонний инструмент: http://www.gentlebytes.com/appledoc/ Apple не предоставляет вам ничего подобного.

---

Прагмы - это функция ISO C для передачи подсказок компилятору.

Единственное добавление прагмы в XCode (AFAIK) - это mark с - и / или текстом.Это создает строку и / или полужирный текст в поиске методов.

// Mark a section in your code with a line and a bold text.
// You can use the line or the text alone.
#pragma mark - random text

Если вы редактируете файлы на языках, которые не компилируются с GCC, вы все равно можете использовать метку в комментариях (это работает для GCCязыки тоже):

// MARK: - random text
/* MARK: more random text */

Но я использую знак #pragma, потому что моя цветовая тема имеет прагмы красного цвета, и они выделяются лучше, чем комментарии.Если вы хотите, чтобы фрагмент кода прагмы был привязан к горячей клавише, используйте

#pragma mark - <#Description#>

, чтобы перейти на вкладку к тексту описания.

Подробнее о прагмах:

• Что такое прагма?
• 6,56 Прагмы Принято GCC
• Clang's Управление диагностикой с помощью прагм
• Атрибуты функций предпочтительнее прагм, потому что вы не можете генерировать прагмы из макросов, а прагма может иметь другое значение в другом компиляторе.

Answer 2

Добавляя к ответу @ jano, используйте формат ниже, чтобы описать функциональность вашего метода.

  /*!
 @function       getEmployeeDetails
 @abstract       getEmployeeDetails
 @discussion     This function will fetch employee details based on employee id
 @param          strEmpId 
 employee unique id
 @result         an Array of Employee
 */

-(NSArray*)getEmployeeDetails:(NSString *)strEmpId{
     /*Do somethings.*/
}