KDoc y Dokka: Documentación Profesional para Android 📚

🧠 Introducción Técnica

La documentación de software ha evolucionado desde archivos de texto separados hasta convertirse en una parte integral del código fuente. En el ecosistema Kotlin, esta integración se logra a través de KDoc (sintaxis) y Dokka (motor de generación).

Entender estas herramientas no es solo cuestión de aprenderse unos tags; es comprender cómo el compilador de Kotlin procesa los metadatos de tu código para generar artefactos útiles tanto para humanos (HTML/Markdown) como para máquinas (IDE Autocomplete).

📝 KDoc: Profundizando en el Estándar

La Diferencia Fundamental con Javadoc

Aunque KDoc se inspira en Javadoc, su diseño refleja la filosofía de Kotlin: concisión y seguridad de tipos.

Mientras Javadoc es puramente textual en muchos aspectos, KDoc permite enlazar símbolos de manera fuerte. Cuando escribes [MyClass], no es solo texto azul; el IDE y Dokka resuelven ese símbolo contra el AST (Abstract Syntax Tree). Si la clase cambia de nombre o paquete, el enlace se rompe o se actualiza (si usas refactoring tools), garantizando la integridad de la documentación.

Sintaxis Avanzada y Tags Semánticos

Más allá de los básicos @param y @return, KDoc ofrece tags que enriquecen la semántica del código:

/**
 * Representa el resultado de una operación de red.
 *
 * @param T El tipo de dato encapsulado en caso de éxito.
 * @property data El payload de la respuesta, si existe.
 * @property error Excepción capturada en caso de fallo.
 *
 * @constructor Privado para forzar el uso de los constructores estáticos [Success] y [Error].
 * @see retrofit2.Response
 */
sealed class NetworkResult<out T> { ... }

Tags menos conocidos pero vitales:

• @receiver: Esencial para Extension Functions. Explica qué estamos extendiendo.
• @suppress: Oculta elementos de la documentación generada (útil para métodos internos o deprecated que aún no se pueden borrar).

Markdown en KDoc

A diferencia de Javadoc que usa HTML embebido (<p>, <code>), KDoc usa Markdown estándar. Esto facilita la lectura directa en el código fuente:

/**
 * Calcula el hash SHA-256.
 *
 * # Algoritmo
 * 1. Convierte el input a ByteArray.
 * 2. Aplica el digest.
 * 3. Formatea a Hex String.
 *
 * Uso:
 * ```kotlin
 * val hash = "password".sha256()
 * ```
 */
fun String.sha256(): String { ... }

🔧 Dokka: El Motor de Generación Bajo el Capó

Arquitectura de Dokka

Dokka no es un simple script de regex. Es una aplicación compleja que:

1. Analiza: Usa las librerías del compilador de Kotlin para entender la estructura del código.
2. Modelado: Crea un modelo intermedio unificado (Dokka Model).
3. Plugins: Permite transformar ese modelo.
4. Renderizado: Genera la salida final (HTML, Jekyll, GFM).

Esta arquitectura permite que Dokka soporte proyectos mixtos Java/Kotlin, entendiendo las interacciones entre ambos lenguajes.

Configuración de Grado Fino (Fine-Tuning)

A menudo, la configuración por defecto no es suficiente para un proyecto profesional.

1. Documentando Paquetes (Package-level docs) Kotlin no tiene package-info.java. Dokka soluciona esto permitiendo incluir archivos Markdown externos.

// build.gradle.kts
dokka {
    dokkaSourceSets.named("main") {
        // Incluye documentación de alto nivel para el módulo
        includes.from("Module.md", "packages.md")
    }
}

2. Enlaces a Fuentes Externas (Cross-referencing) Dokka puede enlazar tus tipos con la documentación oficial de Android o librerías de terceros.

externalDocumentationLink {
    // Si tu función devuelve un 'RecyclerView', el link llevará a developer.android.com
    url.set(URL("https://developer.android.com/reference/"))
    packageListUrl.set(URL("https://developer.android.com/reference/androidx/package-list"))
}

Formatos de Salida: Más allá de HTML

• dokkaHtml: El estándar moderno. Responsivo, con búsqueda integrada y modo oscuro. Ideal para publicar en GitHub Pages.
• dokkaGfm (GitHub Flavored Markdown): Genera archivos .md. Útil si quieres integrar la documentación dentro de un sitio Jekyll o Hugo existente.
• dokkaJavadoc: Genera HTML clásico estilo Java. Útil solo por compatibilidad legacy o requisitos corporativos estrictos.

🏗️ Estrategia de Documentación para Librerías Android

Si estás creando una librería o SDK para otros desarrolladores, la documentación es tu producto.

El Patrón “Sample Code”

Dokka permite incrustar código desde archivos fuente reales, no solo bloques de texto. Esto asegura que tus ejemplos siempre compilen.

Estructura de carpetas:

project/
├── src/main/kotlin/MyLib.kt
└── src/samples/kotlin/MyLibSamples.kt

En MyLib.kt:

/**
 * @sample com.example.samples.MyLibSamples.usageExample
 */
fun complexOperation() { ... }

En build.gradle.kts:

samples.from("src/samples/kotlin")

Si cambias la API y rompes el ejemplo, el build fallará. Esto es Documentación Testeada.

💡 Mejores Prácticas y Errores Comunes

El Anti-Patrón “Comentarios Eco”

Evita documentar lo obvio.

❌ Mal:

/**
 * Obtiene el usuario.
 * @param id El id del usuario.
 * @return El usuario.
 */
fun getUser(id: String): User

Valor añadido: 0. Ruido visual: 100%.

✅ Bien:

/**
 * Recupera el usuario desde el almacenamiento local o remoto.
 * Si el usuario no existe en local, intenta un fetch de red.
 *
 * @throws NoSuchElementException Si el usuario no existe en ninguna fuente.
 */
fun getUser(id: String): User

Documentando para el IDE (IntelliSense)

Recuerda que el 90% de las veces, tu documentación será leída en un pequeño popup en Android Studio (Ctrl+Q).

• Pon la información más importante en la primera frase.
• Usa párrafos cortos.
• Usa listas para enumerar condiciones.

🔗 Conclusión

Dokka y KDoc transforman el código fuente en una base de conocimiento accesible. No son herramientas pasivas; requieren una configuración activa y un mantenimiento consciente.

Al dominar la configuración avanzada de Dokka y la semántica de KDoc, elevas la calidad de tu entregable final. Tu código no solo funciona; enseña a otros cómo usarlo correctamente.