Skip to main content

Generación de documentación

⏱ Dedicación recomendada: 0 minutos
Esto considera el contenido visible y relevante, e ignora texto colapsado o marcado como opcional.

r8vnhill/echo-app-kt

En esta lección, exploraremos cómo generar documentación efectiva para bibliotecas en Kotlin usando Dokka. Aprenderás a configurar Dokka en tu proyecto, generar documentación en distintos formatos y cómo integrarla en el proceso de construcción para mantenerla actualizada. También veremos cómo empaquetar la documentación como parte de tu distribución final, asegurando que sea accesible y fácil de usar para lxs desarrolladorxs que utilicen tu biblioteca.

La documentación es vital​

Una buena documentación facilita el entendimiento y uso de la biblioteca por otrxs desarrolladorxs. Ahorra tiempo y recursos al reducir la necesidad de soporte y consultas frecuentes , mejorando la adopción de la biblioteca, ya que lxs desarrolladorxs prefieren usar herramientas bien documentadas.

Documentación inadecuada​

Una documentación inadecuada puede hacer que lxs usuarixs encuentren difícil entender cómo utilizar la biblioteca correctamente. Esto incrementa los errores y malentendidos, lo que lleva a una percepción negativa de la biblioteca. Como resultado, disminuye la tasa de adopción, ya que lxs desarrolladorxs buscarán alternativas que estén mejor documentadas.

Buena documentación​

Una buena documentación ofrece una visión clara de cómo instalar y empezar a usar la biblioteca, incluyendo ejemplos de código que demuestran sus funciones y características principales. Además, describe en detalle todas las funciones, clases y métodos disponibles, y proporciona ejemplos concretos para explicar cómo la biblioteca resuelve problemas específicos, así como soluciones a preguntas y problemas comunes que lxs usuarixs puedan encontrar.

Es importante mantener un estilo y formato consistente en toda la documentación, asegurando que se actualice con cada nueva versión de la biblioteca. Evita la jerga técnica innecesaria y utiliza un lenguaje claro y directo en las explicaciones. Recoge y aplica el feedback de lxs usuarixs para mejorar continuamente la calidad de la documentación.

Herramientas como Javadoc (Java), KDoc y Dokka (Kotlin), Sphinx (Python), entre otras, facilitan la generación de documentación a partir del código fuente. Publica esta documentación en plataformas accesibles como GitHub Pages, Read the Docs, o sitios web dedicados.

Una buena documentación debe incluir:

  • Instrucciones de instalación y un ejemplo simple de uso.
  • Ejemplos prácticos que muestren diversas funcionalidades de la biblioteca.
  • Descripciones detalladas de todas las funciones, métodos y clases, con ejemplos de uso.
  • Respuestas a preguntas frecuentes y soluciones a problemas típicos.

Documentando lib​

Lo primero que necesitamos para generar documentación es documentación, así que vamos a agregar comentarios de documentación a la biblioteca lib.

lib/src/main/kotlin/com/github/username/echo/Echo.kt
/**
 * Returns a formatted message with the current timestamp and the provided message.
 *
 * This function retrieves the current system time and appends it to the given message, returning the result as a
 * formatted string. The timestamp includes the date and time at the moment the function is called.
 *
 * ## Usage:
 * This function can be used to log messages with a timestamp for debugging or tracking purposes.
 *
 * ### Example:
 * ```kotlin
 * val logMessage = echo("Task started")
 * println(logMessage)
 * ```
 * Output:
 * ```
 * 2024-09-15T10:45:30.123456Z - Task started
 * ```
 *
 * @param message The message to be echoed with the current timestamp.
 * @return A string that combines the current system time with the provided message.
*/
fun echo(message: String) = "${Clock.System.now()} - $message"

Dokka​

Dokka es una herramienta de generación de documentación para proyectos en Kotlin desarrollada por JetBrains. Similar a Javadoc para Java, Dokka convierte los comentarios de documentación en el código Kotlin a varios formatos de salida como HTML, Markdown, Javadoc y más. Esto permite generar documentación detallada y fácil de leer directamente desde el código fuente, facilitando el mantenimiento y la actualización de la documentación.

Características principales de Dokka​

  • Soporte multiplataforma: Dokka es compatible con proyectos que utilizan Kotlin Multiplatform, permitiendo generar documentación para código compartido entre diferentes plataformas como JVM, JS y Native.
  • Integración con Gradle y Maven: Dokka se integra fácilmente con sistemas de construcción como Gradle y Maven, permitiendo generar documentación como parte del proceso de construcción del proyecto.
  • Personalización de estilos y formatos: Ofrece la posibilidad de personalizar el estilo y formato de la documentación generada mediante temas y plantillas, adaptándose a las necesidades específicas del proyecto.
  • Soporte para Java y Kotlin: Dokka puede procesar código escrito tanto en Kotlin como en Java, facilitando la documentación de proyectos mixtos.
  • Generación de documentación tipo Javadoc: Puede generar documentación en formato Javadoc, lo cual es útil para proyectos que requieren mantener consistencia con documentación existente en Java.
  • Extensibilidad mediante Plugins: Dokka permite extender su funcionalidad mediante plugins, lo que facilita la adición de características personalizadas o el soporte para nuevos formatos de salida.

Cómo utilizar Dokka​

Para comenzar a utilizar Dokka, lo primero es agregar el plugin y su versión en nuestro archivo de catálogo de versiones gradle/libs.versions.toml:

gradle/libs.versions.toml
[versions]
# Otras versiones...
dokka = "1.9.20"

[plugins]
# Otros plugins...
dokka = { id = "org.jetbrains.dokka", version.ref = "dokka" }

Aplicar el plugin de Dokka en build.gradle.kts​

Una vez definido en el catálogo, aplicamos el plugin de Dokka en el archivo build.gradle.kts:

build.gradle.kts
plugins {
    // Otros plugins...
    alias(libs.plugins.dokka)
}

val dokkaId = libs.plugins.dokka.get().pluginId

subprojects {
    apply(plugin = dokkaId)
    // Otras configuraciones...
}

Configuración de Dokka​

A continuación, configuramos Dokka en un archivo dokka.conventions.gradle.kts dentro del módulo convention-plugins. Para ello, primero agregamos Dokka como dependencia:

gradle/libs.versions.toml
[libraries]
# Otras librerías...
dokka = { module = "org.jetbrains.dokka:org.jetbrains.dokka.gradle.plugin", version.ref = "dokka" }

Esto nos permite acceder a la API de Dokka desde nuestro archivo de convenciones. Luego, aplicamos el plugin de Dokka en convention-plugins/build.gradle.kts:

convention-plugins/build.gradle.kts
dependencies {
    // Otras dependencias...
    implementation(libs.dokka)
}

Archivo de configuración dokka.conventions.gradle.kts​

Finalmente, creamos el archivo dokka.conventions.gradle.kts en el módulo convention-plugins con la siguiente configuración para la tarea DokkaTask:

convention-plugins/src/main/kotlin/dokka.conventions.gradle.kts
import org.jetbrains.dokka.gradle.DokkaTask

tasks.withType<DokkaTask>().configureEach {
    dokkaSourceSets {
        configureEach {
            reportUndocumented = true
            sourceRoots.from(file("src/main/kotlin"))
            platform = org.jetbrains.dokka.Platform.jvm
        }
    }
    outputDirectory = layout.buildDirectory.dir("dokka/html").get().asFile
}
¿Qué acabamos de hacer?
  • [3]: configureEach permite definir configuraciones comunes para todas las tareas DokkaTask.
  • [5]: Especificamos los conjuntos de fuentes de Dokka.
  • [6]: Dokka generará advertencias para elementos no documentados.
  • [7]: Establecemos el directorio donde se encuentran los archivos fuente (por ejemplo, src/main/kotlin).
  • [8]: Definimos la plataforma para la que se genera la documentación, en este caso, Kotlin JVM.
  • [11]: Indicamos el directorio donde se almacenará la documentación generada en formato HTML.

Generar la documentación​

Ahora debemos agregar el plugin dokka.conventions a la biblioteca de la que queremos generar la documentación, en nuestro caso lib:

lib/build.gradle.kts
plugins {
    // Otros plugins...
    id("dokka.conventions")
}

Con esto, podemos generar la documentación ejecutando la tarea dokkaHtml:

./gradlew :lib:dokkaHtml

La documentación generada estará disponible en el directorio lib/build/dokka/html. Para ver la documentación en un navegador, abre el archivo index.html en tu navegador web. El resultado debiera verse como este ejemplo de documentación de Echo.

Integrando la documentación en el proceso de construcción​

Para integrar la generación de documentación en el proceso de construcción, empaquetaremos la documentación generada en un archivo .jar e incorporaremos la tarea de generación de documentación en la tarea de construcción principal.

Paso 1: Definir la tarea de empaquetado de la documentación​

Primero, definimos una tarea que empaquete la documentación generada por Dokka en un archivo .jar. Esto lo hacemos en el archivo dokka.conventions.gradle.kts:

convention-plugins/src/main/kotlin/dokka.conventions.gradle.kts
// ...
tasks.register<Jar>("dokkaJar") {
    group = "documentation"
    description = "Creates a JAR with the Dokka documentation"
    archiveClassifier = "docs"
    from(tasks.named<DokkaTask>("dokkaHtml").get().outputDirectory)
}

Paso 2: Agregar la tarea dokkaJar a la construcción principal​

Una vez definida la tarea de empaquetado, la agregamos como dependencia de la tarea principal fatJar para que la generación de documentación se ejecute automáticamente como parte del proceso de construcción.

convention-plugins/src/main/kotlin/compile.conventions.gradle.kts
// ...
plugins {
    id("jvm.conventions")
    id("dokka.conventions")
}
// ...
tasks.named("fatJar") {
    dependsOn("dokkaJar")
}

Resultado final​

Al ejecutar la tarea fatJar, se generará tanto el JAR principal como el JAR con la documentación generada por Dokka, asegurando que la documentación se integre completamente en el proceso de construcción.

Bibliografías Recomendadas