Guía de Documentación en Swift - Desappstre

Guía de Documentación en Swift – desappstre http://desappstre.
com/guia-de-documentacion-en-swift/
desappstre
Blog de desarrollo Swift para iOS, macOS, watchOS y tvOS
Guía de Documentación en Swift

PUBLICADO EL 7 JUNIO, 2019 POR ADOLFO
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
Descargas En lugar deM605_Pla…

WSDOSMI… crear un lenguaje
M_125_Co… de M606_Pla…
marcado propio,
examples-… 100% Borrar
1 de 19 11/12/19 5:10 p.m.

Guía de Documentación en Swift – desappstre http://desappstre.com/guia-de-documentacion-en-swift/
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.
Marcador ¿Para qué sirve? Ejemplo
# Indica el título principal # Título 1
## Nivel 2 de título ## Título 2
Descargas
###
WSDOSMI…
Nivel 3 de título
M605_Pla… M_125_Co…
### Título 3
M606_Pla… examples-… 100% Borrar
2 de 19 11/12/19 5:10 p.m.

#### Nivel 4 de título #### Título 4
##### Nivel 5 de título ##### Título 5
###### Nivel 6 de título ###### Título 6
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
¿Para qué Se ve
Marcador Ejemplo
sirve? como…
El texto en
negrita se Es muy Es muy
**
pone entre los **importante** importante
2 asteriscos
En luga de
asteriscos se Es muy Es muy
__
puede usar el __importante__ importante
guión bajo
Cursiva
Se ve
como…
* El texto en cursiva Es muy Es muy

Descargas WSDOSMI… M605_Pla… M_125_Co… M606_Pla… examples-… 100% Borrar
3 de 19 11/12/19 5:10 p.m.

Se ve
como…
se pone entre un
*importante* importante
solo asterisco
En luga de
asteriscos se Es muy Es muy
_
puede usar un _importante_ importante
guión bajo
Citas
Se pone al principio del \> En un lugar de la

\>
párrafo de cita Mancha…
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.
+ Se pone antes de elementos de la lista + Item
– Se pone antes de elementos de la lista - Item
* Se pone antes de elementos de la lista * Item
Para anidar los elementos tenemos que añadir una

4 de 19 11/12/19 5:10 p.m.

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
5 de 19 11/12/19 5:10 p.m.

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
2. iOS
3. Mac
4. Web
5. Despliegue
6. App Store
7. Mac App Store
8. Envío de Press Kit
9. 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
6 de 19 11/12/19 5:10 p.m.

caracteres ` y en el de apertura indicamos el

lenguaje. Por ejemplo…
` ` ` swift
override internal func viewDidLoad() -> Void
{
super.viewDidLoad()
}
```
Se vería como…
1 override internal func viewDidLoad() -> Void
2 {
3 super.viewDidLoad()
5 ...
6 }
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
Descargas lista en el comentario
WSDOSMI… M605_Pla… de un
M_125_Co… y a documentar
M606_Pla… examples-… 100% Borrar
7 de 19 11/12/19 5:10 p.m.

sus variables.
1 /**
2 Posibles resultados al ejecutat una peticion HTTP
3 para el feed de información de incidencias de la EMT.
4
5 Los posibles valores a devolver son:
6
7 - success: Recuperamos el contenido del stream
8 - requestError: Problema en la peticion HTTP
9 - connectionError: Error general
10 */
11 internal enum HttpResult
12 {
13 /// La operacion ha terminado bien.
14 /// Devolvemos el stream de datos reacuperados
15 case success(data: Data, pagination: Pagination?)
16 /// Algo ha salido mal.
17 /// Devolvemos un mensaje con la descripcion del error
18 /// y el codigo HTTP asociado
19 case requestError(code: Int, message: String)
20 /// Problemas de conexión con el servidor
21 case connectionError
22 }
docs_list.swift hosted with ❤ by GitHub view raw
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
8 de 19 11/12/19 5:10 p.m.

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:
1 -Parameter nombreVariable: Y aquí su descripción
2 -Parameter otraVariable: Y aquí otra descripción
o también podemos usar -Parameters en cuyo

caso el formato varía
1 -Parameters:
2 -nombreVariable: Y aquí su descripción
3 -otraVariable: Y aquí otra descripción
1 /**
2 This is the place where all the requests happends.
3
4 There some `StoreRequest` parameters combinations that
5 return no results. That's not an error. It's simply that
6 the combination it's not available at the **iTunes Store**
7
8 - Parameters:
9 - request: Search parameters combination
10 - handler: Results will be put at this place.
11
12 - SeeAlso: song(named:completionHandler:), movie(named:completionHandl
13 */
14 private func storeRequest<T: Codable>(_ request: StoreRequest,
9 de 19 11/12/19 5:10 p.m.

15 {
16 guard let countryCode = self.countryCode else
17 {
18 handler(iTunesResult.error(message: "Where are you from?
19
20 return
21 }
22
23 ...
24 }
docs-parameter.swift hosted with ❤ by GitHub view raw

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.
1 - Throws:
2 - serverUnavailable: Server is not ready
3 - badRequest: The `StoreRequest` objet is not well-formed
1 /**
2 This is the place where all the requests happends.
3
4 There some `StoreRequest` parameters combinations that
5 return no results. That's not an error. It's simply that
6 the combination it's not available at the **iTunes Store**
7
10 de 19 11/12/19 5:10 p.m.

8 - Parameters:
9 - request: Search parameters combination
10 - handler: Results will be put at this place.
11
12 - Throws:
13 - serverUnavailable: Server is not ready
14 - badRequest: The `StoreRequest` objet is not well-formed
15
16 - SeeAlso: song(named:completionHandler:), movie(named:completionHandl
17 */
18 private func storeRequest<T: Codable>(_ request: StoreRequest,
19 {
20 guard let countryCode = self.countryCode else
21 {
22 handler(iTunesResult.error(message: "Where are you from?
23
24 return
25 }
26
27 ...
28 }
docs_throws.swift hosted with ❤ by GitHub view raw
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
1 - Returns: El stream con un formato `JSON` válido
1 /**
2 Corrige el formato del JSON proviniente del API
3 de BiciMAD.
4
11 de 19 11/12/19 5:10 p.m.

5 Parece que la clave `data` incluye el caracter backslash `\`,

6 al igual que las llaves de apertura `{` y cierre `}`
7
8 - Parameter data: El stream de datos devuelto por el servicio
9 - Returns: El stream con un formato `JSON` válido
10 */
11 private func fixJSONResponse(from data: Data) -> Data?
12 {
13 guard var jsonResponse = String(data: data, encoding: .
14 {
15 return nil
16 }
17
18 ...
19
20 return jsonResponse.data(using: .utf8)
21 }
docs-returns.swift hosted with ❤ by GitHub view raw

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
12 de 19 11/12/19 5:10 p.m.

1 - SeeAlso: `fetchTicket(_:)`
Precondition
Describe el estado necesario para que se pueda

ejecutar la función
1 - 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
1 - Postcondition: Tenemos un ticket válido tras la compra
Requires
Los requisitos para una ejecución correcta del

código.
1 - Requires: Que `startDate` sea menor que `endDate`
Version
Un número de versión del código
1 - Version: 1.0.1
Warning
13 de 19 11/12/19 5:10 p.m.

Una advertencia sobre el uso o estado del código
1 - Warning: Cualquier ticket anterior se sobreescribe al terminar.
Important
Hacemos notar algo importante a todo aquel que

use este código.
1 - 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.
1 - Complexity: O(n)
Documentar el A c e r c a d e …
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.
14 de 19 11/12/19 5:10 p.m.

Author
El autor o autores del código
1 - Author: Adolfo Vera (@fitomad)
O si son varios los autores…
1 - Authors:
2 - Adolfo Vera
3 - Jorge Vera
Copyright
Información sobre los derechos de autor o la

licencia a la que está sujeto el código
1 - Copyright: 2018 Adolfo Vera. MIT License
Date
Una fecha, puede ser la de creación, la de última

modificación…
1 - 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
Descargas
descripciónM605_Pla…
WSDOSMI…
del código.
M_125_Co… M606_Pla… examples-… 100% Borrar
15 de 19 11/12/19 5:10 p.m.

1 - Keyword: TicketMaster, Star Wars, The Big Bang Theory, Apple Pay.
Note
Es información relacionada sobre el código.
1 - 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
16 de 19 11/12/19 5:10 p.m.

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.
1 import Foundation
2
3 //
4 // MARK: - TaskInfo
5 //
6
7 ...
8
9 //
10 // MARK: - Tasks
11 //
12
13 ...
14
15 //
16 // MARK: - Sessions
17 //
18
19 ...
20
17 de 19 11/12/19 5:10 p.m.

21 //
22 // MARK: - Goals
23 //
24
25 ...
26
27 //
28 // MARK: - Thieves
29 //
30
31 ...
32
33 //
34 // MARK: - Work Activities
35 //
36
37 ...
38
39 //
40 // MARK: - Migration
41 //
42
43 ...
44
45 //
46 // MARK: - iCloud Errors
47 //
48
49 ...
docs-mark.swift hosted with ❤ by GitHub view raw
Y en Xcode veremos…
18 de 19 11/12/19 5:10 p.m.

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
Publicado en Swift
Tema Founder para WordPress por Compete Themes.
19 de 19 11/12/19 5:10 p.m.

Guía de Documentación en Swift - Desappstre

Cargado por

Información del documento

Título original

Derechos de autor

Formatos disponibles

Compartir este documento

Compartir o incrustar documentos

Opciones para compartir

¿Le pareció útil este documento?

¿Este contenido es inapropiado?

Copyright:

Formatos disponibles

Guía de Documentación en Swift - Desappstre

Cargado por

Copyright:

Formatos disponibles

Guía de Documentación en Swift – desappstre http://desappstre.

Guía de Documentación en Swift

Una de las tareas a la que menos tiempo

Bien por falta de tiempo o por dejadez siempre

Los ingenieros de Swift, sabedores de ese

Todo comienza con Markdown

Descargas En lugar deM605_Pla…

1 de 19 11/12/19 5:10 p.m.

los creadores de Swift decidieron que era mejor

Markdown es un lenguaje de marcado

Es decir, que junto con nuestro texto plano

A continuación os dejo una pequeña guía con la

Siempre deben ir al inicio del párrafo.

Marcador ¿Para qué sirve? Ejemplo

# Indica el título principal # Título 1

## Nivel 2 de título ## Título 2

2 de 19 11/12/19 5:10 p.m.

Marcador ¿Para qué sirve? Ejemplo

#### Nivel 4 de título #### Título 4

##### Nivel 5 de título ##### Título 5

###### Nivel 6 de título ###### Título 6

Sólo hay disponibles seis niveles de titulado.

* El texto en cursiva Es muy Es muy

3 de 19 11/12/19 5:10 p.m.

Marcador ¿Para qué sirve? Ejemplo

Se pone al principio del \> En un lugar de la

Podemos generar listas ordenadas, desordenadas

Marcador ¿Para qué sirve? Ejemplo

+ Se pone antes de elementos de la lista + Item

– Se pone antes de elementos de la lista - Item

* Se pone antes de elementos de la lista * Item

Para anidar los elementos tenemos que añadir una

4 de 19 11/12/19 5:10 p.m.

tabulación al elemento para establecer la jerarquía.

Las listas ordenadas se crean usando números

5 de 19 11/12/19 5:10 p.m.

Encerrando el código entre el caracter ` marcamos

También podemos añadir código de más de una

6 de 19 11/12/19 5:10 p.m.

caracteres ` y en el de apertura indicamos el

1 override internal func viewDidLoad() -> Void

Hay que tener en cuanta que el soporte para

Documentación con Swift

Ahora que sabemos como darle formato a nuestra

7 de 19 11/12/19 5:10 p.m.

docs_list.swift hosted with ❤ by GitHub view raw

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

Documentar Parámetros, Variables de

Esto es lo que va a ocupar el 99% del tiempo que

8 de 19 11/12/19 5:10 p.m.

primero que necesitamos saber es que para

El marcador para los parámetros es -Parameter y

1 -Parameter nombreVariable: Y aquí su descripción

2 -Parameter otraVariable: Y aquí otra descripción

o también podemos usar -Parameters en cuyo

2 -nombreVariable: Y aquí su descripción

3 -otraVariable: Y aquí otra descripción

9 de 19 11/12/19 5:10 p.m.

docs-parameter.swift hosted with ❤ by GitHub view raw

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

Si nuestra fución lanza un error podemos

2 - serverUnavailable: Server is not ready

3 - badRequest: The `StoreRequest` objet is not well-formed

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

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