¿Swift tiene soporte para la generación de documentación?

238

Muchos lenguajes soportan comentarios de la documentación para permitir un generador (como javadoco doxygen ) para generar documentación de código mediante el análisis de ese mismo código.

¿Swift tiene algún tipo de comentario de documentación como este?

pconcepcion
fuente
Sabiendo que Xcode con Objective-C permite comentarios de documentación, creo que Apple agregará esta opción a Xcode con rapidez en el futuro cercano (sin embargo, es solo una suposición, no tengo evidencia)
Garoal
@ Δdeveloper suponía lo mismo, pero como no he visto ninguna referencia, me preguntaba si alguien puede confirmarlo y también si habrá alguna herramienta de documentación específica.
pconcepcion
1
Definitivamente agregarán algo en el futuro, el // MARK:comentario también está programado para una futura versión de Xcode.
Leandros
El estilo Doxygen comenta un tipo de trabajo para los métodos de clase, con ~ varias ~ MUCHAS ADVERTENCIAS. Por mi parte, seguiré usando el estilo Doxygen (como lo hice para Obj-C) y espero que Xcode mejore su soporte para ellos.
Pascal
1
Para documentar los parámetros de bloque, consulte stackoverflow.com/a/41970146/1054573
Leonard Pauli

Respuestas:

386

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:
///
/// ![Swift Logo](/Users/Stuart/Downloads/swift.png "The logo for the Swift programming language")
///
/// - 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."
}

Ayuda rápida de documentación de Swift


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:

/// ![Alt Text](http://www.example.com/alt-image.jpg)

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

Stuart
fuente
1
Parece que el comportamiento cambió en la versión final de Xcode 6.3 (6D570). Los bloques sangrados ahora están formateados como bloques de código y pueden anidarse con más de dos niveles.
NexD.
2
Muy buena descripción de la sintaxis de documentación de Swift 2.0. Debería actualizar la publicación para incluir el/// - todo: keyword
Leonardo
2
@uchuugaka En realidad no. Es posible que se haya basado anteriormente en reStructuredText, pero a partir de la documentación de Xcode 7 los comentarios se basan en Markdown, con el mismo formato básico que los comentarios del patio de recreo. Consulte las Notas de la versión de Xcode 7 para más detalles.
Stuart
2
¿Hay alguna forma de vincular a otras funciones en el mismo archivo, como lo hace JavaDoc? Por ejemplo, "vea la myOtherMethod(param1:)funcionalidad extendida"
Ben Leggiero
1
@BenLeggiero, sí, usando /// - Tag: otherMethody [otherMethod](x-source-tag://otherMethod). Para más detalles, mira mi respuesta .
Clay Ellis
58

Aquí hay algunas cosas que funcionan para documentar el código rápido 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 es de 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.

ShakenManChild
fuente
2
Mattt Thompson escribió un artículo sobre esto , y cree que es así reStructuredText.
Eonil
En el ejemplo anterior, los símbolos más (+) y menos (-) también actuarán como viñetas, además de los asteriscos mostrados.
Vince O'Sullivan
Parece que ///se requiere una línea de comentario en blanco ( ) entre cualquier texto explicativo y las líneas :param:o :returns:. Omitir esto hace que XCode (6.1.1 en el momento de la escritura) incluya la ayuda del parámetro en el cuerpo principal de la descripción de la función.
Robin Macharg
Desafortunadamente, esto no funciona con Xcode 7 Beta. Esperemos que lo arreglen en una versión de lanzamiento.
stevo.mit
1
Xcode 7 adoptó una sintaxis diferente: ericasadun.com/2015/06/14/swift-header-documentation-in-xcode-7
Zmey
41

Nuevo en Xcode 8 , puede seleccionar un método como este

func foo(bar: Int) -> String { ... }

Luego presione command+ option+/ o elija "Estructura" - "Agregar documentación" del menú "Editor" de Xcode, y generará la siguiente plantilla de comentarios para usted:

/// <#Description#>
///
/// - parameter bar: <#bar description#>
///
/// - returns: <#return value description#>
Logan Jahnke
fuente
Gracias por esto. Solo mencionaré que el método abreviado de teclado que indica no parece funcionar en un teclado danés, donde "/" es shift- "7".
RenniePet
27

Swift incluye el manejo de comentarios "///" (aunque probablemente todavía no lo sea todo).

Escribe algo como:

/// Hey!
func bof(a: Int) {

}

Luego, haga clic en el nombre de la función y listo :)

Jean Le Moignan
fuente
11

Puedo confirmar que ShakenManChild ha proporcionado una solución peopr

¡Solo asegúrate de tener una línea vacía debajo de la descripción!

Una situación inválida

Forma apropiada

De otra manera

Otro estilo de comentario

DAH
fuente
8

Si. 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#>.
*/
Jakub Truhlář
fuente
6

He encontrado algo interesante, cavando en el binario Xcode. Archivos con el final .swiftdoc. Definitivamente tiene documentos, porque estos archivos contienen los documentos para Swift UIKit / Foundation API, desafortunadamente parece ser un formato de archivo propietario, para usar en el visor de documentación en Xcode.

Leandros
fuente
5

En Xcode Editor -> Estructura -> Agregar documentación.

ingrese la descripción de la imagen aquí

Abo3atef
fuente
Sí, ha sido mencionado hace más de 3 meses por Logan Jahnke .
Franklin Yu
-1

Tal vez sea una buena idea echarle un ojo a AppleDoc o al propio HeaderDoc de Apple, que no se reconoce mucho. Todavía puedo encontrar algunas sugerencias de HeaderDoc en el terminal 10.9 Mavericks (headerdoc2html)

Recomiendo leer la última " Novedades de Xcode " * (no estoy seguro si todavía está bajo NDA) * El enlace apunta a la versión Xcode 5.1 que contiene información sobre HeaderDoc también.

TiBooX
fuente
-1

A partir de Xcode 5.0, se admiten los comentarios estructurados de Doxygen y HeaderDoc.

Fuente

Matt Zanchelli
fuente
1
Bueno, estaba preguntando sobre Swift en este caso.
pconcepcion
@pconcepcion ¿Estás usando Swift en Xcode? Entonces sí.
Matt Zanchelli
1
Matt, por lo que sé (puedo estar equivocado) Swift no es compatible hasta Xcode 6 beta, por lo que no estoy seguro de si la documentación para Xcode 5 es válida para Xcode 6 (y para Swift)
pconcepcion
@pconcepcion Funciona. He estado usando la misma documentación de doxygen de estilo que en Objective-C y funciona. Por encima de un método o propiedad, uso /// This is what the method does.etc.
Matt Zanchelli
Ok, entonces la cosa es que lo has probado en Xcode 6. Estaba confundido porque estabas hablando de Xcode 5 y el enlace es para Xcode 5
pconcepcion