Documentación en Android: KDoc, Dokka y Flujo de Trabajo Profesional 📚

La documentación no es un “extra” opcional; es la diferencia entre un proyecto mantenible a largo plazo y una deuda técnica impagable. En el desarrollo Android profesional, a menudo nos centramos en la arquitectura limpia y los tests, pero olvidamos que el código es un medio de comunicación entre humanos, no solo instrucciones para una máquina.

¿Por qué documentamos? No es solo para explicar “qué” hace el código (eso debería ser obvio por el nombre de la función), sino para explicar el “por qué”, las limitaciones, los edge cases y las decisiones de diseño.

En este artículo, elevaremos el nivel de tu documentación utilizando las herramientas estándar del ecosistema: KDoc y Dokka, integrándolas en un pipeline de CI/CD robusto.

🧠 Teoría: La Filosofía de la Documentación en Código

Antes de escribir una sola línea de KDoc, entendamos los niveles de documentación:

1. Nivel Código (Self-documenting code): Nombres de variables y funciones claros. Necesario, pero no suficiente.
2. Nivel Función/Clase (KDoc): Contratos, invariantes, pre-condiciones, post-condiciones y excepciones.
3. Nivel Arquitectura (Module Docs): Cómo interactúan los componentes grandes entre sí (Dokka Module.md).
4. Nivel Producto (Wiki/Guides): Tutoriales y guías de alto nivel.

El objetivo de KDoc es cubrir el Nivel 2. Una buena documentación de API reduce el “Bus Factor” (qué pasa si el único dev que sabe esto se va) y acelera el onboarding.

🔹 KDoc: El Estándar de Documentación Kotlin

KDoc combina la sintaxis de Javadoc con la flexibilidad de Markdown. Es analizado directamente por el compilador de Kotlin y por el IDE.

Anatomía Técnica de un KDoc Perfecto

Un bloque KDoc no es solo texto; es estructura de datos semántica.

/**
 * Clase que representa un usuario en el sistema de autenticación.
 *
 * [User] es una entidad inmutable que garantiza la integridad de los datos
 * personales. Se utiliza como Value Object a través de todas las capas
 * de la arquitectura (Domain, Data, UI).
 *
 * ## Invariantes
 * - El [email] siempre está normalizado a minúsculas.
 * - El [id] nunca puede ser una cadena vacía.
 *
 * @property id Identificador único (UUID v4).
 * @property name Nombre completo para mostrar en UI.
 * @property email Dirección validada.
 * @constructor Valida las invariantes al instanciar. Lanza [IllegalArgumentException] si fallan.
 * 
 * @see com.example.auth.AuthManager
 * @since 1.0.0
 */
data class User(
    val id: String,
    val name: String,
    val email: String
) {
    init {
        require(id.isNotBlank()) { "User ID cannot be blank" }
    }
}

Por qué usar [] (Brackets)

Observa el uso de [User], [email], [id].

• Teoría: Esto crea enlaces simbólicos en el AST (Abstract Syntax Tree) de la documentación.
• Práctica: Si refactorizas el nombre de la propiedad email a emailAddress, el IDE actualizará automáticamente la referencia en el KDoc. Si usaras texto plano, la documentación quedaría obsoleta al instante.

Tags Avanzados y Su Importancia

Tag	Propósito Teórico	Uso Práctico
@receiver	Documenta el objeto this en extension functions.	Crucial para entender qué estamos extendiendo.
@throws	Declara las excepciones chequeadas y no chequeadas.	Fundamental para que el consumidor sepa qué errores capturar.
@sample	Enlaza a código compilable real.	Garantiza que los ejemplos en la doc nunca tengan errores de sintaxis (porque son tests reales).

/**
 * Extensión segura para parsear fechas.
 *
 * @receiver String con formato ISO-8601.
 * @return [LocalDate] o null si el formato es inválido.
 * @sample com.example.samples.DateSamples.parseDateSafe
 */
fun String.parseDateSafe(): LocalDate? { ... }

🔹 Dokka: El Motor de Generación

Dokka es a Kotlin lo que Javadoc es a Java, pero con superpoderes. No solo extrae los comentarios; analiza la estructura semántica de tu código Kotlin (incluyendo corrutinas, flows y tipos de plataforma).

Cómo Funciona Internamente

Dokka utiliza el compilador de Kotlin en modo de análisis (frontend) para construir un modelo de todo tu código. Luego, utiliza “plugins” para renderizar ese modelo en diferentes formatos (HTML, GFM, Javadoc). Esto significa que Dokka “entiende” tu código tan bien como el compilador.

Configuración Profesional Multi-Módulo

En una arquitectura limpia (Clean Architecture), tendrás módulos como app, domain, data. Configurar Dokka para unificar todo es vital.

// root/build.gradle.kts
plugins {
    id("org.jetbrains.dokka") version "1.9.20"
}

// Configuración unificada
tasks.dokkaHtmlMultiModule {
    outputDirectory.set(file("docs/api"))
    moduleName.set("SuperApp Documentation")
}

Para cada sub-módulo, personalizamos la experiencia:

// domain/build.gradle.kts
dokka {
    dokkaSourceSets.named("main") {
        // Enlaza automáticamente a la documentación oficial de Android y Kotlin
        // Si tu código retorna un `Flow`, el link llevará a la web de Kotlin Coroutines.
        externalDocumentationLink {
            url.set(URL("https://kotlinlang.org/api/kotlinx.coroutines/"))
        }

        // Incluye documentación conceptual extra (Markdown)
        includes.from("Module.md")
    }
}

El Archivo Module.md

KDoc documenta clases. Module.md documenta paquetes y módulos. Crea un archivo Module.md en la raíz de tu módulo:

# Módulo Domain

Este módulo contiene la **Lógica de Negocio Pura**.
- No tiene dependencias de Android Framework.
- Define los [UseCases] y las interfaces de [Repository].

## Paquetes Principales
- `model`: Entidades de dominio.
- `usecase`: Casos de uso interactivos.

Esto da contexto de alto nivel que KDoc no puede dar.

🚀 Automatización: CI/CD y Validación

La documentación que no se valida, se pudre. Necesitamos integrarla en el ciclo de vida del desarrollo.

Validación de Cobertura de Docs (Doc Coverage)

No permitas código nuevo sin documentar. Podemos usar un script simple o herramientas como Dokka en modo validación (aunque Dokka per se no falla si falta docs, podemos usar herramientas de análisis estático).

Una técnica efectiva es usar Detekt con reglas personalizadas o configuración estricta para comentarios.

O un script simple en CI:

      - name: 📊 Documentation Coverage
        run: |
          # Contamos funciones públicas vs funciones documentadas
          # (Script simplificado para demostración)
          TOTAL_FUNCS=$(grep -r "fun " src/main | wc -l)
          DOC_FUNCS=$(grep -r "/\*\*" src/main | wc -l)
          echo "Coverage: $DOC_FUNCS / $TOTAL_FUNCS"

GitHub Actions Workflow: “Docs as Code”

El siguiente workflow trata la documentación como un artefacto de primera clase, igual que el APK.

name: Docs Publisher

on:
  push:
    branches: [main]
    paths: ['**.kt', '**.md'] # Solo corre si cambia código o docs

jobs:
  publish-docs:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      
      - name: Generate Dokka Html
        run: ./gradlew dokkaHtmlMultiModule
        
      - name: Deploy to GitHub Pages
        uses: peaceiris/actions-gh-pages@v3
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          publish_dir: ./docs/api

💎 Mejores Prácticas: De Bueno a Excelente

1. Documenta la Asincronía

En Android, saber si una función bloquea o suspende es vital.

/**
 * Obtiene el perfil del usuario.
 * 
 * ⚠️ Esta es una operación de red.
 * @return [Flow] que emite actualizaciones en tiempo real.
 * NUNCA colectar en el hilo principal sin [flowOn].
 */
fun getUserStream(): Flow<User>

2. KDoc para Propiedades, no solo Funciones

/**
 * Tiempo máximo en milisegundos antes de timeout.
 * Valor por defecto: 3000ms (3 segundos).
 */
const val TIMEOUT_MS = 3000L

3. Evita Comentarios Redundantes (DRY)

❌ MAL:

/**
 * Establece el nombre.
 * @param name El nombre.
 */
fun setName(name: String)

✅ BIEN:

/**
 * Actualiza el nombre de visualización.
 * Dispara una recomposición de la UI si el valor cambia.
 * @throws ValidationException si el nombre contiene caracteres prohibidos.
 */
fun setDisplayName(name: String)

🎯 Conclusión

La documentación profesional en Android es un ecosistema compuesto por intención (KDoc), herramientas (Dokka) y procesos (CI/CD).

Al adoptar KDoc y Dokka, no solo estás “escribiendo comentarios”; estás construyendo una base de conocimiento navegable, interconectada y viva que escala con tu equipo. Transforma la documentación de una tarea odiada a una ventaja competitiva.

Empieza hoy: Configura el plugin de Dokka en tu build.gradle y corre ./gradlew dokkaHtml. El resultado te sorprenderá.