Escritura de documentación para proyectos Kotlin: de la A a la Z

Introducción: por qué la documentación es importante para un proyecto Kotlin

Escribir documentación no es solo una formalidad, sino un elemento clave para el éxito de un proyecto Kotlin. El código bien documentado acelera la incorporación de nuevos desarrolladores, simplifica el mantenimiento y reduce la cantidad de errores. Kotlin, al ser un lenguaje moderno, ofrece potentes herramientas para crear documentación: KDoc (análogo de JavaDoc) y Dokka (generador de documentación). En este artículo, analizaremos el ciclo completo de escritura de documentación para un proyecto Kotlin: desde los comentarios en el código hasta la publicación de la documentación final.

Independientemente de si trabajas en una biblioteca, una API o una aplicación interna, seguir las mejores prácticas de documentación hará que tu código sea claro y accesible. Comencemos con lo básico.

Fundamentos de KDoc: sintaxis y estructura

KDoc es un lenguaje de marcado para documentar código Kotlin. Está basado en JavaDoc, pero adaptado a las características de Kotlin: seguridad contra nulos, funciones de extensión, propiedades y lambdas. Los comentarios KDoc comienzan con /** y terminan con */.

Estructura básica de un comentario KDoc

Cada comentario KDoc consta de una descripción y etiquetas opcionales. Las etiquetas principales son:

\n
• @param — descripción del parámetro de la función
\n
• @return — descripción del valor de retorno
\n
• @throws o @exception — descripción de la excepción
\n
• @see — enlace a otro elemento
\n
• @sample — inserción de un ejemplo de código
\n
• @property — descripción de una propiedad de clase
\n
• @constructor — descripción del constructor
\n
• @receiver — descripción del receptor para funciones de extensión
\n

Ejemplo de un comentario KDoc simple:

/**\n * Calcula el factorial de un número dado.\n *\n * Utiliza un enfoque iterativo para evitar el desbordamiento de pila.\n * Solo funciona con números enteros no negativos.\n *\n * @param n Número entero no negativo para el cual se calcula el factorial\n * @return Factorial del número n (n!)\n * @throws IllegalArgumentException si n < 0\n */\nfun factorial(n: Int): Long {\n    require(n >= 0) { "n must be non-negative" }\n    var result = 1L\n    for (i in 2..n) {\n        result *= i\n    }\n    return result\n}

Documentación de propiedades y clases

Para clases y propiedades, utiliza la etiqueta @property:

/**\n * Representa un usuario del sistema.\n *\n * @property id Identificador único del usuario\n * @property name Nombre completo del usuario\n * @property email Dirección de correo electrónico\n * @property isActive Indicador de actividad de la cuenta\n */\ndata class User(\n    val id: Long,\n    val name: String,\n    val email: String,\n    val isActive: Boolean = true\n)

Generación de documentación con Dokka

Dokka es la herramienta oficial para generar documentación de Kotlin. Soporta varios formatos de salida: HTML, Markdown, Javadoc y JSON. Dokka puede manejar proyectos multiplataforma y muestra correctamente las construcciones específicas de Kotlin.

Configuración de Dokka en Gradle

Para agregar Dokka a un proyecto, conecta el plugin en build.gradle.kts:

plugins {\n    id("org.jetbrains.dokka") version "1.9.20"\n}\n\ntasks.dokkaHtml {\n    outputDirectory.set(buildDir.resolve("dokka"))\n    moduleName.set("My Kotlin Library")\n}\n\ntasks.dokkaJavadoc {\n    outputDirectory.set(buildDir.resolve("javadoc"))\n}

Después de esto, ejecuta el comando ./gradlew dokkaHtml — la documentación se generará en la carpeta build/dokka.

Funcionalidades avanzadas de Dokka

Dokka admite la personalización de la apariencia, la inclusión/exclusión de paquetes y la adición de páginas adicionales. Ejemplo de configuración con perso