¿Swift tiene soporte para la generación de documentación?
documentation-generation (11)
Muchos idiomas admiten comentarios de documentación para permitir que un generador (como javadoc o doxygen ) genere documentación de código al analizar ese mismo código.
¿Tiene Swift alguna característica de comentario de documentación de tipo como esta?
A partir de Xcode 5.0, se admiten los comentarios estructurados de Doxygen y HeaderDoc.
Aquí hay algunas cosas que funcionan para documentar el código Swift en Xcode 6. Es muy defectuoso y sensible a los dos puntos, pero es mejor que nada:
class Foo {
/// This method does things.
/// Here are the steps you should follow to use this method
///
/// 1. Prepare your thing
/// 2. Tell all your friends about the thing.
/// 3. Call this method to do the thing.
///
/// Here are some bullet points to remember
///
/// * Do it right
/// * Do it now
/// * Don''t run with scissors (unless it''s tuesday)
///
/// :param: name The name of the thing you want to do
/// :returns: a message telling you we did the thing
func doThing(name : String) -> String {
return "Did the /(name) thing";
}
}
Lo anterior se representa en la Ayuda rápida como cabría esperar con listas numéricas formateadas, viñetas, parámetros y documentación de valor de retorno.
Nada de esto está documentado. Presente un radar para ayudarlos a avanzar.
He encontrado algo interesante, cavando en el binario de Xcode. Archivos con la terminación .swiftdoc . Definitivamente tiene documentos, porque estos archivos contienen los documentos para Swift UIKit / Foundation API, desafortunadamente parece ser un formato de archivo propietario, para uso en el visor de documentación en Xcode.
Los comentarios de la documentación se admiten de forma nativa en Xcode, produciendo documentación representada de forma inteligente en la Ayuda rápida (tanto en la ventana emergente cuando se pulsan 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 en el área de juegos, por lo que gran parte de lo que puede hacer en áreas de juego ahora se puede usar directamente en la documentación del código fuente.
Para obtener detalles completos de la sintaxis, consulte Referencia de formato de marcado . Tenga en cuenta que hay algunas discrepancias entre la sintaxis de los comentarios de juegos y la documentación de símbolos; estos se señalan en el documento (por ejemplo, las citas en bloque solo se pueden usar en los patios de recreo).
A continuación se muestra un ejemplo y una lista de los elementos de sintaxis que funcionan actualmente para los comentarios de documentación de símbolos.
Actualizaciones
Xcode 7 beta 4 ~ Se agregó " - Throws: ... " como un elemento de la lista de nivel superior que aparece junto con los parámetros y descripciones de retorno en la Ayuda rápida.
Xcode 7 beta 1 ~ Algunos cambios significativos en la sintaxis con Swift 2: los comentarios de la documentación ahora se basan en Markdown (igual que en los parques infantiles).
Xcode 6.3 (6D570) ~ El texto con sangría ahora se formatea como bloques de código, con las sangrías posteriores anidadas. 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 pegará al final de la última línea con cualquier carácter.
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 /** */ (bloque) son compatibles para generar comentarios de documentación. Aunque personalmente prefiero el estilo visual de /** */ comments, la sangría automática de Xcode puede arruinar el formato de este estilo de comentario al copiar / pegar, ya que elimina los espacios en blanco principales. Por ejemplo:
/**
See sample usage:
let x = method(blah)
*/
Al pegar, la sangría de 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 uso /// , y lo usaré para el resto de los ejemplos en esta respuesta.
Elementos de bloque
Título:
/// # My Heading
o
/// My Heading
/// ==========
Subtítulo:
/// ## My Subheading
o
/// My Subheading
/// -------------
Regla horizontal:
/// ---
Listas desordenadas (con viñetas):
/// - An item
/// - Another item
También puedes usar + o * para listas desordenadas, solo tiene que ser consistente.
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 linea
É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.
Campo de golf:
/// [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 consigo que funcionen las rutas de archivo 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 solo 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 que se muestren de manera prominente en la Ayuda rápida. Estas palabras clave de marcado en su mayoría toman el formato - <keyword>: (la excepción es el parameter , que también incluye el nombre del parámetro antes de los dos puntos), donde la palabra clave en sí puede escribirse 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 por encima 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 la 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, puedes escribir cada parámetro de esta manera:
/// - parameter <#parameter name#>:
Símbolo Descripción Campo palabras clave
La siguiente lista de palabras clave se muestran 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. También vea la lista completamente documentada de palabras clave y sus usos previstos en la sección Comandos de campos de descripción de símbolos de la Referencia de formato de marcado .
Atribuciones:
/// - author:
/// - authors:
/// - copyright:
/// - date:
Disponibilidad:
/// - since:
/// - version:
Admoniciones:
/// - 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:
Exportacion de documentacion
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 usando 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.
Puedo confirmar que ShakenManChild ha proporcionado una solución peopr
Solo asegúrate de que tienes una línea vacía debajo de la descripción.
Sí. Base común (hice fragmentos con el equivalente de Obj-C)
C objetivo:
/**
@brief <#Short description - what it is doing#>
@discussion <#Description#>
@param <#paramName#> <#Description#>.
@return <#dataType#> <#Description#>.
*/
Rápido
/**
<#Short inline description - what it is doing#>
<#Description#>
:param: <#paramName#> <#Description#>.
:returns: <#dataType#> <#Description#>.
*/
Si solo estás usando Swift, entonces vale la pena mirar a Jazzy.
Swift incluye el manejo de comentarios "///" (aunque probablemente no todo todavía).
Escribe algo como:
/// Hey!
func bof(a: Int) {
}
Luego oprima y haga clic en el nombre de la función y voilà :)
Tal vez sea una buena idea tener un ojo en AppleDoc o en el propio HeaderDoc Apple que no se reconoce mucho. Todavía puedo encontrar algunos consejos de HeaderDoc en la terminal de Mavericks 10.9 (headerdoc2html)
Recomiendo leer el último " Novedades en Xcode " * (no estoy seguro de si todavía está bajo NDA) * El enlace apunta a la versión Xcode 5.1 que también contiene información sobre HeaderDoc.
Nuevo en Xcode 8 , puedes seleccionar un método como este
func foo(bar: Int) -> String { ... }
Luego presione command + option + / o elija "Estructura" - "Agregar documentación" en el menú "Editor" de Xcode, y generará la siguiente plantilla de comentarios para usted:
/// <#Description#>
///
/// - parameter bar: <#bar description#>
///
/// - returns: <#return value description#>