pro - Comentarios rápidos de la documentación

scanner pdf gratis iphone

Question

Tengo algunas preguntas sobre los comentarios de la documentación de Swift.

1. ¿Hay alguna forma de hacer una sección de declaraciones relacionadas como la documentación de Apple? Por ejemplo, cuando opción + hago clic en el método tablewView (_: heightForRowAtIndexPath :), me vincula a otros 3 métodos relacionados dentro de la documentación generada.

2. ¿Hay alguna etiqueta de advertencia en swift? Sé que en object-c le permitió hacer @warning y obtener una advertencia en negrita en la documentación que se genera. Sin embargo,: advertencia: no hace nada en los comentarios de documentación rápida, así que tenía curiosidad por si había otra manera.

3. ¿Hay alguna manera de convertir su documentación en un archivo HTML que tenga un formato similar al de la Documentación de Apple? Sé que en otros IDE para otros idiomas, como Eclipse, simplemente puede generar documentación html para su código. ¿XCode tiene esto?

Answer 1

(3) Para generar su documentación en HTML (o incluso generar documentos), le recomiendo encarecidamente que se haya creado para ese propósito.

Incluso si todavía es WIP, funciona muy bien y genera documentación con una presentación similar a la documentación de Apple.

Answer 2

Para el código Swift, Apple eliminó HeaderDoc y cambió a una sintaxis de estilo Markdown . Eligieron la variante CommonMark de Markdown con algunas extensiones de palabras clave específicas de Swift.

Documentacion de simbolos

Hay cuatro secciones, de las cuales, solo se incluye siempre la descripción:

• Descripción
• Parámetros
• Tiros
• Devoluciones

Después de la descripción, el orden de las otras secciones no importa. Solo puedes tener una sección de Tiros y una de Devoluciones.

/**
 What does this function do?

 - Parameters:
   - firstParam: Describe the first param
   - secondParam: Describe the second param
 - Returns: true or false
 - Throws: SomeError you might want to catch
 */
func someFunction(firstParam: String, secondParam: String) throws -> Bool {
    return true;
}

Guía rápida de palabras clave

Si desea obtener fantasía, hay una larga lista de palabras clave que puede incluir en cualquier lugar de la descripción.

- Attention: - Author: - Authors: - Bug: - Complexity: - Copyright:
- Date: - experiment: - important: - invariant: - Note: - Precondition:
- Postcondition: - Remark: - Requires: - seealso: - Since: - Todo: - Version:
- Warning:

Para generar documentos automáticamente, presione ⌘ comando + ⌥ opción + / o Editor -> Structure -> Add Documentation

Lea más aquí: https://useyourloaf.com/blog/swift-documentation-quick-guide/

Answer 3

Puede utilizar el markup para escribir comentarios en el área de juegos y en la documentación del código.

• Para la documentación de juegos ricos use //: o /*: */
• Para la documentación del código use /// o /** */

Ejemplo

/// This function returns a *hello* string for a given `subject`.
///
/// - Warning: The returned string is not localized.
///
/// Usage:
///
///     println(hello("Markdown")) // Hello, Markdown!
///
/// - Parameter subject: The subject to be welcomed.
///
/// - Returns: A hello string to the `subject`.
func hello(subject: String) -> String {
    return "Hello, /(subject)!"
}

Respuestas a tus preguntas.

Anuncio. 1. No. Si bien hay una etiqueta de marca SeeAlso , aún no es lo suficientemente inteligente como para vincularla a los símbolos relacionados dentro de su biblioteca o de terceros.

Anuncio. 2. Sí, hay una etiqueta de marca de Warning . Ver mi ejemplo anterior.

Anuncio. 3. Aunque Xcode puede generar una representación XML de los comentarios de la documentación , no puede generar un archivo HTML. Recomiendo usar jazzy para eso.

Answer 4

Xcode 7.0 beta 4

La notación ha sido cambiada ( :param: ya no funciona ...)

/// Creates the string representation of the poo with requested size.
///
/// - warning: Be carefull! Poos can hurt.
/// - parameter size: requested size of the poo
/// - returns: string representation of the poo
func makePoo(size: String) -> String
{
    return "Ouch. This is /(size) poo!"
}

Y se parece a esto:

Puedes usar /// o /** */