Documente la API para ambos equipos

Tanto los desarrolladores de Android como los de iOS utilizan su código compartido, por lo que una documentación clara es tan importante como las propias funciones. 📝

KDoc es el comentario de documentación de Kotlin. Se escribe justo encima de una declaración y las herramientas lo convierten en páginas de referencia fáciles de leer.

El código muestra qué ocurre; una buena documentación explica el motivo y el uso previsto. Indique qué debe esperar quien llama al código, no cómo funciona internamente.

Use la etiqueta @param para describir cada entrada. Así, quienes llaman al código desde cualquiera de las dos aplicaciones saben exactamente qué deben pasar sin leer el código fuente.

La etiqueta @return describe lo que se devuelve. Una explicación clara evita suposiciones incorrectas sobre unidades, rangos o valores nulos.

Rodee los nombres con corchetes para crear enlaces, como [Quote]. Los lectores podrán ir directamente a los tipos relacionados en la documentación generada.

Un pequeño ejemplo es mejor que varios párrafos de texto. Un fragmento que muestre una llamada real responde a la mayoría de las preguntas antes de que se formulen.

Dedique su esfuerzo a la superficie pública. Las funciones auxiliares internas pueden tener pocos comentarios, ya que ningún equipo externo las utilizará.

Los desarrolladores de Swift también leen su KDoc, así que describa el comportamiento con términos sencillos. Evite la jerga de JVM que no significa nada en el lado de iOS.

Dokka lee su KDoc y produce un sitio navegable. Ambos equipos obtienen una referencia compartida en lugar de tener que deducir el comportamiento a partir del código.

Una documentación desactualizada puede inducir más a error que no tener documentación. Actualice el KDoc en el mismo cambio que el código para que nunca se desvíen.

Escriba KDoc para su API pública, explique el motivo, documente los parámetros y los valores devueltos, añada un ejemplo y deje que Dokka lo comparta con ambos equipos. 🎉