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?

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."
}

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

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.

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#>

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 :)

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!

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#>.
*/

Si solo usas Swift, entonces vale la pena mirar a Jazzy.

https://github.com/realm/jazzy

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.

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

Jazzy puede ayudar a generar hermosa documentación con estilo de manzana. Aquí hay una aplicación de muestra con detalles sobre cómo usar y configurar rápidamente.

https://github.com/SumitKr88/SwiftDocumentationUsingJazzy

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.

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

Fuente