Los comentarios de documentación se admiten de forma nativa en Xcode, lo que produce documentación renderizada de forma inteligente en la Ayuda rápida (tanto en el ⌥símbolo emergente al hacer clic en los símbolos como en el Inspector de ayuda rápida ⌥⌘2).
Los comentarios de la documentación de símbolos ahora se basan en la misma sintaxis de Markdown utilizada por los ricos comentarios de juegos, por lo que mucho de lo que puede hacer en los juegos ahora se puede usar directamente en la documentación del código fuente.
Para obtener todos los detalles de la sintaxis, consulte Referencia de formato de marcado . Tenga en cuenta que existen algunas discrepancias entre la sintaxis para los comentarios enriquecidos del patio de juegos y la documentación de símbolos; estos se señalan en el documento (por ejemplo, las comillas en bloque solo se pueden usar en parques infantiles).
A continuación se muestra un ejemplo y una lista de los elementos de sintaxis que actualmente funcionan para comentarios de documentación de símbolos.
Actualizaciones
Xcode 7 beta 4 ~ Se agregó " - Throws: ..." como elemento de lista de nivel superior que aparece junto con los parámetros y las descripciones de retorno en la Ayuda rápida.
Xcode 7 beta 1 ~ Algunos cambios significativos a la sintaxis con Swift 2 - comentarios de documentación ahora basados en Markdown (igual que los parques infantiles).
Xcode 6.3 (6D570) ~ El texto sangrado ahora está formateado como bloques de código, con anidaciones posteriores. Parece que no es posible dejar una línea en blanco en un bloque de código de este tipo; al intentar hacerlo, el texto se pega al final de la última línea con cualquier carácter en él.
Xcode 6.3 beta ~ El código en línea ahora se puede agregar a los comentarios de la documentación mediante backticks.
Ejemplo para Swift 2
/// Text like this appears in "Description".
///
/// Leave a blank line to separate further text into paragraphs.
///
/// You can use bulleted lists (use `-`, `+` or `*`):
///
/// - Text can be _emphasised_
/// - Or **strong**
///
/// Or numbered lists:
///
/// 7. The numbers you use make no difference
/// 0. The list will still be ordered, starting from 1
/// 5. But be sensible and just use 1, 2, 3 etc…
///
/// ---
///
/// More Stuff
/// ==========
///
/// Code
/// ----
///
/// Use backticks for inline `code()`. Indentations of 4 spaces or more will create a code block, handy for example usage:
///
/// // Create an integer, and do nothing with it
/// let myInt = 42
/// doNothing(myInt)
///
/// // Also notice that code blocks scroll horizontally instead of wrapping.
///
/// Links & Images
/// --------------
///
/// Include [links](https://en.wikipedia.org/wiki/Hyperlink), and even images:
///
/// 
///
/// - note: That "Note:" is written in bold.
/// - requires: A basic understanding of Markdown.
/// - seealso: `Error`, for a description of the errors that can be thrown.
///
/// - parameters:
/// - int: A pointless `Int` parameter.
/// - bool: This `Bool` isn't used, but its default value is `false` anyway…
/// - throws: A `BadLuck` error, if you're unlucky.
/// - returns: Nothing useful.
func doNothing(int: Int, bool: Bool = false) throws -> String {
if unlucky { throw Error.BadLuck }
return "Totally contrived."
}
Sintaxis para Swift 2 (basado en Markdown )
Estilo de comentario
Los comentarios de estilo ///(en línea) y /** */(en bloque) son compatibles para producir comentarios de documentación. Si bien personalmente prefiero el estilo visual de los /** */comentarios, la sangría automática de Xcode puede arruinar el formato de este estilo de comentarios al copiar / pegar, ya que elimina los espacios en blanco iniciales. Por ejemplo:
/**
See sample usage:
let x = method(blah)
*/
Al pegar, la sangría del bloque de código se elimina y ya no se representa como código:
/**
See sample usage:
let x = method(blah)
*/
Por esta razón, generalmente lo uso ///, y lo usaré para el resto de los ejemplos en esta respuesta.
Elementos de bloque
Bóveda:
/// # My Heading
o
/// My Heading
/// ==========
Subtítulo:
/// ## My Subheading
o
/// My Subheading
/// -------------
Regla horizontal:
/// ---
Listas no ordenadas (con viñetas):
/// - An item
/// - Another item
También puede usar +o *para listas desordenadas, solo tiene que ser coherente.
Listas ordenadas (numeradas):
/// 1. Item 1
/// 2. Item 2
/// 3. Item 3
Bloques de código:
/// for item in array {
/// print(item)
/// }
Se requiere una sangría de al menos cuatro espacios.
Elementos en línea
Énfasis (cursiva):
/// Add like *this*, or like _this_.
Fuerte (negrita):
/// You can **really** make text __strong__.
Tenga en cuenta que no puede mezclar asteriscos ( *) y guiones bajos ( _) en el mismo elemento.
Código en línea:
/// Call `exampleMethod(_:)` to demonstrate inline code.
Enlaces:
/// [Link Text](https://en.wikipedia.org/wiki/Hyperlink)
Imágenes:
/// 
La URL puede ser una URL web (usando "http: //") o una URL de ruta de archivo absoluta (parece que no puedo conseguir que funcionen las rutas de archivos relativas).
Las URL para enlaces e imágenes también se pueden separar del elemento en línea para mantener todas las URL en un lugar manejable:
/// A [link][1] an an ![image][2]
///
/// ...
///
/// [1]: http://www.example.com
/// [2]: http://www.example.com/image.jpg
Palabras clave
Además del formato Markdown, Xcode reconoce otras palabras clave de marcado para mostrar de manera destacada en la Ayuda rápida. Estas palabras clave de marcado en su mayoría toman el formato - <keyword>:(la excepción es parameter, que también incluye el nombre del parámetro antes de los dos puntos), donde la palabra clave en sí se puede escribir con cualquier combinación de caracteres en mayúscula / minúscula.
Palabras clave de la sección de símbolos
Las siguientes palabras clave se muestran como secciones destacadas en el visor de ayuda, debajo de la sección "Descripción" y arriba de la sección "Declarado en". Cuando se incluye, su orden se fija como se muestra a continuación, aunque puede incluirlos en el orden que desee en sus comentarios.
Consulte la lista completamente documentada de palabras clave de sección y sus usos previstos en la sección Comandos de la sección de símbolos de la Referencia de formato de marcado .
/// - parameters:
/// - <#parameter name#>:
/// - <#parameter name#>:
/// - throws:
/// - returns:
Alternativamente, puede escribir cada parámetro de esta manera:
/// - parameter <#parameter name#>:
Símbolo Descripción Campo palabras clave
La siguiente lista de palabras clave se muestra como encabezados en negrita en el cuerpo de la sección "Descripción" del visor de ayuda. Aparecerán en el orden en que los escriba, como en el resto de la sección "Descripción".
Lista completa parafraseada de este excelente artículo de blog de Erica Sadun. Consulte también la lista completamente documentada de palabras clave y sus usos previstos en la sección Comandos de campo de descripción de símbolo de la Referencia de formato de marcado .
Atribuciones:
/// - author:
/// - authors:
/// - copyright:
/// - date:
Disponibilidad:
/// - since:
/// - version:
Advertencias:
/// - attention:
/// - important:
/// - note:
/// - remark:
/// - warning:
Estado de desarrollo:
/// - bug:
/// - todo:
/// - experiment:
Cualidades de implementación:
/// - complexity:
Semántica Funcional:
/// - precondition:
/// - postcondition:
/// - requires:
/// - invariant:
Referencia cruzada:
/// - seealso:
Exportando Documentación
La documentación HTML (diseñada para imitar la propia documentación de Apple) se puede generar a partir de la documentación en línea utilizando Jazzy , una utilidad de línea de comandos de código abierto.
$ [sudo] gem install jazzy
$ jazzy
Running xcodebuild
Parsing ...
building site
jam out ♪♫ to your fresh new docs in `docs`
Ejemplo de consola tomado de este artículo de NSHipster
