Documentación en Kotlin: escribe código que habla por sí mismo

Documentación en proyectos Kotlin: el arte de ser comprendido

Imagina: abres un proyecto Kotlin de otra persona. El código es bonito, conciso, pero... no entiendes para qué sirve esa función ni qué devuelve. ¿Te suena familiar? Ahora imagina que ese proyecto es tuyo, pero seis meses después. La documentación en Kotlin no es solo cortesía con los colegas. Es una inversión en el futuro de tu código.

En este artículo, analizaremos las mejores prácticas para documentar proyectos Kotlin. Aprenderás a usar KDoc, Dokka y comentarios simples para que tu código hable por sí mismo. ¡Allá vamos!

¿Por qué la documentación en Kotlin no es aburrida?

Kotlin es un lenguaje creado para las personas. Se lee como inglés y su sintaxis elimina el código boilerplate. Pero incluso el código más elegante puede ser un misterio sin documentación. Especialmente cuando se trata de:

\n
• Lógicas de negocio complejas;
\n
• Librerías y API que usan otros desarrolladores;
\n
• Proyectos Android con un ciclo de vida largo;
\n
• Soluciones empresariales donde la rotación de personal es normal.
\n

Una buena documentación Kotlin resuelve tres tareas: explica «qué» hace el código, «por qué» lo hace y «cómo» usarlo. Sin ella, corres el riesgo de tener código que nadie quiere tocar (ni siquiera tú mismo).

KDoc: la herramienta principal para documentar Kotlin

KDoc es el equivalente de JavaDoc para Kotlin. Usa comentarios del tipo /** ... */ y soporta Markdown. Es el estándar de facto para la documentación en proyectos Kotlin.

Así se ve un ejemplo básico:

/**\n * Calcula el descuento para un usuario según su nivel.\n *\n * @param price Precio original del producto.\n * @param userLevel Nivel del usuario (BRONZE, SILVER, GOLD).\n * @return Precio final con descuento.\n * @throws IllegalArgumentException Si price es negativo.\n */\nfun calculateDiscount(price: Double, userLevel: UserLevel): Double {\n    // lógica\n}

Observa: KDoc usa las etiquetas @param, @return, @throws. Pero a diferencia de JavaDoc, puedes escribir Markdown directamente dentro del comentario. Esto es útil para listas, enlaces y formato.

Mejores prácticas de KDoc

\n
• Escribe para personas, no para máquinas. No dupliques lo obvio del código. En lugar de // establece el valor escribe // Establece el valor que se usará para calcular los impuestos.
\n
• Documenta la API pública. Las funciones internas (private o internal) se pueden documentar brevemente o no documentarse.
\n
• Usa @see y @sample. Haz referencia a funciones relacionadas o ejemplos de uso.
\n
• No olvides @receiver para funciones de extensión.
\n

Dokka: convierte comentarios en documentación atractiva

Dokka es un generador de documentación para Kotlin. Puede crear HTML, Markdown, JavaDoc e incluso documentación para proyectos multiplataforma. Si escribes una librería o trabajas en equipo, Dokka es tu mejor amigo.

La instalación es sencilla. En build.gradle.kts, añade el plugin:

plugins {\n    id("org.jetbrains.dokka") version "1.9.20"\n}

Luego ejecuta el comando:

./gradlew dokkaHtml

Dokka generará una carpeta build/dokka/html con una documentación atractiva que incluye todos tus comentarios KDoc, la jerarquía de clases e incluso enlaces a los fuentes.

Consejos para Dokka

\n
• Configura el logotipo y la descripción del proyecto en dokkaConfiguration;
\n
• Usa @suppress para ocultar elementos no deseados