Um dos novos recursos do Xcode 5 é a capacidade de documentar seu próprio código com uma sintaxe de comentário especial. O formato é semelhante ao doxygen, mas parece suportar apenas um subconjunto desses recursos .

Quais comandos são suportados e quais não?
Algum de seus usos difere do doxygen?

Aqui está um exemplo de todas as opções que encontrei no Xcode 5.0.2

Isso foi gerado com este código:

/** First line text.

 Putting \\n doesn't create a new line.\n One way to create a newline is by making sure nothing is on that line. Not even a single space character!

 @a Italic text @em with @@a or @@em.

 @b Bold text with @@b.

 @p Typewritter font @c with @@p or @@c.

 Backslashes and must be escaped: C:\\foo.

 And so do @@ signs: user@@example.com

 Some more text.
 @brief brief text
 @attention attention text
 @author author text
 @bug bug text
 @copyright copyright text
 @date date text
 @invariant invariant text
 @note note text
 @post post text
 @pre pre text
 @remarks remarks text
 @sa sa text
 @see see text
 @since since text
 @todo todo text
 @version version text
 @warning warning text

 @result result text
 @return return text
 @returns returns text


 @code
// code text
while (someCondition) {
    NSLog(@"Hello");
    doSomething();
}@endcode
 Last line text.

 @param param param text
 @tparam tparam tparam text
 */
- (void)myMethod {}

Notas:

• Os comandos devem ser em um /** block */, /*! block */ou com o prefixo ///ou //!.
• Os comandos funcionam com o prefixo @( estilo headerdoc ) ou \( estilo doxygen ). (Ou seja, @be \bambos fazem a mesma coisa.)
• Os comandos geralmente vêm antes do item que estão descrevendo. (Ou seja, se você está tentando documentar a propriedade, o comentário deve vir antes do @propertytexto.) Eles podem vir depois, na mesma linha, com /*!<, /**<, //!<, ///<.
• Você pode adicionar documentação a classes, funções, propriedades e variáveis .
• Todos esses comandos aparecem em texto verde escuro para indicar que são comandos válidos, exceto @returns.
• Pode ser necessário criar seu projeto (ou reiniciar o Xcode) antes que as alterações mais recentes em sua documentação apareçam.

Onde ver a documentação:

1. Durante o código completo, você verá o texto breve:

Isso mostrará o texto breve (sem formatação); se não houver texto breve, ele mostrará uma concatenação de todo o texto até o primeiro @block; se não existir nenhum (por exemplo, você começa com @return), ele concatiza todo o texto eliminando todos os comandos @.

2. Clique com o botão direito do mouse no nome de um identificador:

3. No painel Inspetor de Ajuda Rápida

(Veja a primeira captura de tela.)

4. Em Doxygen

Como os comandos no Xcode 5 são compatíveis com o Doxygen, você pode fazer o download e usar o Doxygen para gerar arquivos de documentação.

Outras notas

Para uma introdução geral ao Doxygen e como documentar o código Objective-C, esta página parece ser um bom recurso.

Descrições de alguns dos comandos suportados:

• @brief: irá inserir texto no início do campo de descrição e é o único texto que aparecerá durante o preenchimento do código.

O seguinte não funciona:

• \n: não gera uma nova linha. Uma maneira de criar uma nova linha é garantir que não haja nada nessa linha. Nem mesmo um caractere de espaço único!
• \example

O seguinte não é suportado (eles nem aparecem em verde escuro):

• \citar
• \ docbookonly
• \ enddocbookonly
• \ endinternal
• \ endrtfonly
• \ endsecreflist
• \ idlexcept
• \ mscfile
• \ refitem
• \ relatedalso
• \ rtfonly
• \ secreflist
• \curto
• \ snippet
• \índice
• \ vhdlflow
• \ ~
• \ "
• .
• ::
• \

Palavras-chave reservadas da Apple:

A Apple usa o que parece ser palavras-chave reservadas que só funcionam em sua documentação. Embora eles apareçam em verde escuro, parece que não podemos usá-los como a Apple. Você pode ver exemplos do uso da Apple em arquivos como AVCaptureOutput.h.

Aqui está uma lista de algumas dessas palavras-chave:

• @abstract, @availibility, @class, @discussion, @deprecated, @method, @property, @protocol, @related, @ref.

Na melhor das hipóteses, a palavra-chave causará uma nova linha no campo Descrição (por exemplo, @discussion). Na pior das hipóteses, a palavra-chave e qualquer texto a seguir não aparecerão na ajuda rápida (por exemplo, @class).

O Swift 2.0 usa a seguinte sintaxe:

/**
        Squares a number.

        - parameter parameterName: number The number to square.

        - returns: The number squared.
    */

Observe como @paramestá agora - parameter.

Agora você também pode incluir marcadores na sua documentação:

/**
        - square(5) = 25
        - square(10) = 100
    */

Sensível:

Pode ser necessário criar seu projeto antes que as alterações mais recentes em sua documentação apareçam.

Às vezes isso não foi suficiente para mim. Fechar o Xcode e abrir o projeto de backup normalmente corrige esses casos.

Também estou obtendo resultados diferentes em arquivos .he arquivos .m. Não consigo obter novas linhas quando os comentários da documentação estão em um arquivo de cabeçalho.

A maior parte da formatação foi alterada para o Swift 2.0 (a partir do Xcode7 ß3, também verdadeiro no ß4)

ao invés de :param: thing description of thing (como no Swift 1.2)

é agora - parameter thing: description of thing

A maioria das palavras-chave foi substituída por em - [keyword]: [description]vez de :[keyword]: [description]. Atualmente a lista de palavras-chave que não funcionam inclui, abstract, discussion, brief, pre, post, sa, see, availability, class, deprecated, method, property, protocol, related, ref.