Documentación de código SWIFT utilizando Markdown

Entre todas las características que Xcode 7 incorpora, hay uno que se distingue; y es la nueva y revolucionaria forma para escribir la documentación del código. Con la introducción de Xcode 7 los desarrolladores pueden utilizar la sintaxis Markdown para aplicar formato de texto enriquecido en su documentación, que en combinación con las palabras claves (como parámetros, resultados de función, etc) puede dar lugar a un sorprendente resultado. Se proporciona un mayor nivel de personalización del texto, es más flexible y, por supuesto, más interesante.

Documentar el código es una tarea extremadamente importante para todos los desarrolladores. A pesar de que parece que se cala el proceso de desarrollo, es en realidad una parte de ella. No voy a estar en desacuerdo que escribir la documentación apropiada y completa para cada propiedad individual, función, clase, estructura, o cualquier otra cosa que existe en un proyecto no es un trabajo fácil. Sin embargo, escribiendo la documentación apropiada se puede:

• Describir el propósito de las propiedades, funciones y clases hasta el nivel de detalle que se desea. Por otra parte, es el mejor lugar para describir las condiciones, casos o requisitos para sus funciones.
• Resaltar las entradas y salidas (parámetros y valores de retorno) de sus métodos.
• Recordar lo que cada función se supone debe hacer y para que sirve cada propiedad y lograr de esta manera que al visitar unos meses después tu aplicación puedas entender lo que hace la misma.
• Que sea fácil para otros desarrolladores entender cómo usar el código cuando se comparte o hacer sus propias bibliotecas.
• Producir manuales de aspecto profesional utilizando herramientas hechas para esta razón (por ejemplo Jazzy).

La documentación de código que se escribe en Xcode se puede previsualizar de tres maneras diferentes:

1. Por Option/Alt-Clicking en el nombre de una propiedad, método, clase, etc. La vista previa Quick Look aparecerá justo encima o por debajo del nombre.
2. Al colocar el cursor en la propiedad, método o el nombre de una clase y abriendo el Inspector de ayuda rápida.
3. Mediante el uso de herramientas de terceros que producirán un manual para ti. Por ejemplo, Jazzy es una herramienta de este tipo, y vamos a discutir sobre ello más adelante. Mediante su uso, la documentación se compila en páginas web, creando un sitio web independiente como una subcarpeta dentro de la carpeta de tu proyecto.

La documentación de código no es tallada en piedra; esta tiene que ser fluida y cambiar de acuerdo a las modificaciones que se realizan en las respectivas entidades (propiedades, métodos, clases, estructuras, enumeraciones). Es casi una regla que si no se agrega la documentación en el momento de la creación de una nueva entidad, entonces es casi seguro que nunca se hará. Por lo tanto, tratar de acostumbrarse al hábito de documentar su código en el momento adecuado y ponerle el tiempo adicional que requiere, trae sus beneficios.

La sintaxis básica de Markdown

Para hacer el mejor uso del nuevo estilo de documentación es importante tener el conocimiento mínimo de la sintaxis de Markdown. Puedes encontrar una gran cantidad de información haciendo una búsqueda sencilla en google acerca de Markdown, sin embargo me parece necesario mencionar al menos los conceptos básicos. No es mi intención, por supuesto, proporcionar una guía completa sobre el mismo; es sólo un esfuerzo por presentar el material más común.

Por lo tanto, usted probablemente sabe (o lo que se aprende en este momento) que la sintaxis Markdown utiliza caracteres especiales para dar formato a un texto, por la adición de recursos (como enlaces e imágenes) y por tener bloques especiales de texto (como listas ordenadas o desordenadas, o bloques de código). Esos caracteres son fáciles de recordar, pero siempre se puede refrescar la memoria mediante la búsqueda en Internet o utilizando la siguiente lista. Sería interesante subrayar aquí que si uno se acostumbra a la sintaxis de rebajas (y de hecho es fácil de hacer eso), a continuación, utilizando el editor adecuado puede producir documentos en diferentes formatos, para las páginas HTML de ejemplo, documentos PDF y más . Hablando de HTML, Markdown soporta HTML en línea, lo que significa que puede escribir etiquetas HTML directamente en el texto, y que se representará correctamente. Sin embargo, el uso de HTML no es la esencia de Markdown, así que vamos a seguir con su propia sintaxis.

Para mas información pueden leer el articulo original en ingles: www.appcoda.com