Este tipo de documentación será la que explique el código de nuestro proyecto. Al hacer clic en Product > Build documentation se compila automátiamente un archivo .docc con la lista de entidades de tu código: métodos, clases, etc. y se abrirá la ventana de documentación oficial de Apple. El nuestro será el primer archivo de documentación que aparezca en la lista, donde la primera vez que compilemos nos aparecerá solo una página vacía, que más adelante tendremos que personalizar, y el código automáticamente dividido en clases, funciones, etc.
Además, en Xcode nos aparecerá en la raíz de nuestro proyecto un archivo .docc con el nombre del proyecto, que contendrá un archivo markdown con el nombre del proyecto y una carpeta llamada Resources, donde podremos arrastrar todas las imágenes u otros recursos que vayamos a usar en la documentación:
Por defecto, la página principal de nuestro proyecto contendrá el siguiente contenido en markdown:
# `Nombre_del_proyecto`
Summary
## Overview
Text
## Topics
### Group
- `Symbol`
Como con cualquier otro documento de markdown, se puede ir maquetando al gusto, pero lo interesante de esta parte es el poder organizar tu código por “Topics” de forma manual. Swift DocC organiza el código de forma automática de forma básica, pero desde esta página, añadiendo debajo de ## Topics un conjunto de grupos de métodos, hará que se organicen en el árbol de nuestra documentación, por ejemplo:
## Topics
### SDK Integration
High-level methods for initializing the SDK, enabling logs, and setting up your environment.
- ``EMMA/startSession(with:)``
- ``EMMA/isSessionStarted()``
- ``EMMA/startSessionBackground(configuration:)``
- ``EMMA/reset()``
- ``EMMA/getSDKVersion()``
- ``EMMA/getSDKBuildVersion()``
- ``EMMA/setDebuggerOutput(visible:)``
### User Tracking & Profiles
Functions to identify, track, and enrich your app users for analytics and retargeting.
- ``EMMA/enableUserTracking()``
- ``EMMA/disableUserTracking(deleteUser:)``
- ``EMMA/isUserTrackingEnabled()``
- ``EMMA/getUserInfo(resultBlock:)``
- ``EMMA/getUserId(resultBlock:)``
- ``EMMA/deviceId()``
- ``EMMA/requestTrackingWithIdfa()``
- ``EMMA/setCustomerId(customerId:)``
- ``EMMA/trackExtraUserInfo(info:)``
- ``EMMA/setUserLanguage(_:)``
De este modo, un usuario que esté integrando EMMA puede navegar más directamente a un método que esté relacionado con el apartado que está implementando en su app, ya que haciendo clic sobre el método marcado con metodo() se redireccionará automáticamente a su descripción en la documentación.
Estructura mejorada al añadir topics en el .md del proyecto
Visualización de los métodos tras dividirlos por Topics en el .md del proyecto
Para documentar el código en archivos de Swift DocC, se utilizarán tres barras /// , y de esta forma una descripción para el método aparecerá en la documentación:
Previsualización de un método
Swift DocC utiliza markdown, y gracias a esto podemos enriquecer visualmente y descriptivamente el código, pudiendo añadir ejemplos de código, recuadros de advertencia, etc.
Una plantilla para documentar un método podría ser la siguiente:
/// Descripción corta del método
///
/// Descripción más detallada sobre el método. Si no se indica
/// un título con '###Titulo personalizado', aparecerá por defecto
/// el título 'Discussion'
///
/// ```swift
/// EMMA.funcionEjemplo("eMMa") // ejemplo de código insertado
/// // Devuelve: 'Hola eMMa'
/// ```
/// - **Parameter** ejemploDeParametro: descripción del parámetro
/// - **Returns**: descripción de lo que devuelve la función
**@available**(iOS 14.0, *) //desde qué versión de iOS está disponible
**public** **static** **func** funcionEjemplo(ejemploDeParametro: String) -> String {
**return** "Hola \\(ejemploDeParametro)"
}
Xcode 13 ofrece la opción de pre-visualizar el código documentado:
Previsualización de un método con parámetros, returns y un ejemplo de código