Una de las tareas a la que menos tiempo dedicamos los desarrolladores (y yo me incluyo) es a escribir documentación en nuestro archivos de código fuente Swift.

Bien por falta de tiempo o por dejadez siempre dejamos de añadir comentarios que llegado el día que tengamos que modificar ese mismo archivo nos serían muy útiles para entender qué hacía esa función o porqué habíamos puesto ese bucle en ese momento determinado.

Los ingenieros de Swift, sabedores de ese pequeño defecto que tenemos, añadieron un soporte estupendo al lenguaje para que pudieramos añadir ayuda a nuestro código y que además interactue con Xcode. Así que vamos a dar un repaso a todas las opciones que tenemos y a ver cómo añadirlas a nuestros archivos.

Todo comienza con Markdown

En lugar de crear un lenguaje de marcado propio, los creadores de Swift decidieron que era mejor emplear uno existente y de amplia difusión, así que dotaron a los comentarios del lenguaje de soporte Markdown.

Markdown es un lenguaje de marcado ligero creado por John Gruber que trata de conseguir la máxima legibilidad y facilidad de publicación tanto en su forma de entrada como de salida.

Es decir, que junto con nuestro texto plano podemos incluir los marcadores de Markdown para dar un formato más profesional a nuestros comentarios.

A continuación os dejo una pequeña guía con la sintáxis básica de Markdown. Al final del artículo encontraréis un enlace con una guía más detallada por si os interesa o la necesitáis.

Encabezados

Siempre deben ir al inicio del párrafo.

El resultado sería…

Título Principal

Título 2

Título 3

Título 4

Título 5

Título 6

Sólo hay disponibles seis niveles de titulado.

Negrita

Cursiva

Citas

Se vería así

En un lugar de la Mancha…

Listas

Podemos generar listas ordenadas, desordenadas y en ambos casos podemos anidar listas dentro de otras. Vamos a verlo.

Para anidar los elementos tenemos que añadir una tabulación al elemento para establecer la jerarquía. Por ejemplo…

- Diseño
- iOS
- Mac
- Web
- Desarrollo
- Interface
- Controladores
- Framework
- Despliegue

Se ve como…

• Diseño
  • iOS
  • Mac
  • Web
• Desarrollo
  • Interface
  • Controladores
  • Framework
• Despliegue

Las listas ordenadas se crean usando números seguidos por un punto como indicador de elemento. Es importante que el primer elemento sea siempre el número 1, el resto no tienen porque ir en orden. Por ejemplo…

1. Pruebas
1. iOS
2. Mac
3. Web
2. Despliegue
1. App Store
2. Mac App Store
3. Envío de Press Kit
4. Seguimiento

Se ve como…

1. Pruebas
   1. iOS
   2. Mac
   3. Web
2. Despliegue
   1. App Store
   2. Mac App Store
3. Envío de Press Kit
4. Seguimiento

Código embebido

Encerrando el código entre el caracter ` marcamos esa parte del texto como código fuente. Por ejemplo, ` let nombre = “Adolfo” ` se vería como let nombre = "Adolfo"

También podemos añadir código de más de una línea, incluso podemos indicar el lenguaje en el que lo estamos escribiendo. Para ello debemos encerrar el parrafo con el código con los tres caracteres ` y en el de apertura indicamos el lenguaje. Por ejemplo…

` ` ` swift
override internal func viewDidLoad() -> Void
{
super.viewDidLoad()
}
` ` `

Se vería como…

override internal func viewDidLoad() -> Void
{
    super.viewDidLoad()

    ...
}

Hay que tener en cuanta que el soporte para resaltado de lenguaje no está disponible en todos los visores de Markdown.

Documentación con Swift

Ahora que sabemos como darle formato a nuestra documentación vamos empezar de documentar nuestro código. El primer ejemplo que vamos a ver es muy sencillo, simplemente vamos a meter una lista en el comentario de un Enum y a documentar sus variables.

Podéis ver el código completo en este archivo de GitHub.

Documentar Parámetros, Variables de Retorno y Throws.

Esto es lo que va a ocupar el 99% del tiempo que pasemos documentando nuestro código. Lo primero que necesitamos saber es que para documentarlos necesitamos usar unos marcadores específicos.

Parámetros

El marcador para los parámetros es -Parameter y su formato es:

-Parameter nombreVariable: Y aquí su descripción
-Parameter otraVariable: Y aquí otra descripción

o también podemos usar -Parameters en cuyo caso el formato varía

-Parameters:
    -nombreVariable: Y aquí su descripción
    -otraVariable: Y aquí otra descripción

Podéis ver el código completo en este archivo de GitHub.

Throws

Si nuestra fución lanza un error podemos documentar los diferentes tipos de errores mediante el marcador Throws seguido de la lista de errores que podemos generar y una descripción de cada uno de ellos.

- Throws:
    - serverUnavailable: Server is not ready
    - badRequest: The `StoreRequest` objet is not well-formed

Valores de Retorno

Si la función devuelve un valor éste se puede documentar con el marcador Return seguido de la descripción de lo que se devuelve por parte de la función

- Returns: El stream con un formato `JSON` válido

Podéis ver el código completo en este archivo de GitHub.

Otros marcadores

Además de los los vistos anteriormente hay otros marcadores que puden sernos de utilidad a la hora de hacer notar alguna particularidad en nuestro código.

SeeAlso

Añade un referencia a otras funciones, tipos, etc. del código

- SeeAlso: `fetchTicket(_:)`

Precondition

Describe el estado necesario para que se pueda ejecutar la función

- Precondition: Debemos tener un *token* válido del servidor

Postcondition

Describe el estado en el que debe quedar el sistema tras ejecutar la función

- Postcondition: Tenemos un ticket válido tras la compra

Requires

Los requisitos para una ejecución correcta del código.

- Requires: Que `startDate` sea menor que `endDate`

Version

Un número de versión del código

- Version: 1.0.1

Warning

Una advertencia sobre el uso o estado del código

- Warning: Cualquier ticket anterior se sobreescribe al terminar.

Important

Hacemos notar algo importante a todo aquel que use este código.

- Important: Se procede al cargo del importe del ticket mediante **Apple Pay**

Complexity

Indica la complejidad del algoritmo a la hora de ejecutarse para que nos hagamos una idea cómo puede influir en el rendimiento de la app o framework.

- Complexity: O(n)

Documentar el Acerca de…

Existen otros marcadores que sirven para que podamos indicar información tal como el autor o autores del código, el copyright, notas sonre lo que se ha escrito… No es información sobre el código en si, pero nos puede servir por si necesitamos ponernos en contacto con quien escribió ese código.

Author

El autor o autores del código

- Author: Adolfo Vera (@fitomad)

O si son varios los autores…

- Authors:
    - Adolfo Vera
    - Jorge Vera

Copyright

Información sobre los derechos de autor o la licencia a la que está sujeto el código

- Copyright: 2018 Adolfo Vera. MIT License

Date

Una fecha, puede ser la de creación, la de última modificación…

- Date: Created -> 02/12/2018 Modified: 03/12/2018

Keyword

Se usa para establecer palabras claves por las que puede buscar que no están presentes en la descripción del código.

- Keyword: TicketMaster, Star Wars, The Big Bang Theory, Apple Pay.

Note

Es información relacionada sobre el código.

- Note: Cualquier problema con el token hay que dirigirse a Sistemas.

¿Y cómo veo esto en Xcode?

Sólo tienes que pulsar con el ratón o el trackpad en el nombre de la función, clase, estructura… mientras pulsas la tecla OPTION en tu teclado. Al hacerlo verás algo como esto:

Creando secciones en el código

Si habéis escrito código en Objective-C seguro que os suena la directiva del preprocesador #pragma mark. Pues bien, en Swift tal directiva no existe, pero si que tiene un homólogo en forma del // MARK: o // MARK: - si queremos incluir una barra de separación horizontal en el explorador de funciones de Xcode.

Con esto podemos crear secciones en nuestro código que nos van a permitir navegar por él de una forma más cómoda y sencilla. Vamos a verlo con un ejemplo, primero vamos a ver el código y luego podrás ver una imagen del explorar de funciones de Xcode donde verás como divide las diferentes secciones.

Y en Xcode veremos…

Conclusión

Y recordad añadir comentarios, vuestro yo del futuro os lo agradecerá eternamente.

Enlaces de interés

• Guía de la sintaxis de Markdown.
• Cálculo de la complejidad de un algoritmo