Cómo simplificar la documentación de Android con Dokka y KDoc | por Pooja | febrero 2023

Todos los buenos productos vienen con un manual de instrucciones para facilitar a los usuarios el uso del producto. Un producto fácil de usar puede marcar una gran diferencia. Esto también se aplica a la escritura de cualquier software. Para los desarrolladores, comprender el código tiene un gran impacto en la creación de aplicaciones fáciles de usar con la funcionalidad correcta. En esta publicación de blog, puede ver cómo usar Dokka y KDoc para simplificar la documentación de Android y facilitar que otros desarrolladores trabajen con su código. Repasaremos los conceptos básicos y le mostraremos cómo usarlo para crear documentación de Android bien organizada y fácil de usar.Flujo de trabajo de dokka [made with canva]La documentación del código es la descripción que ayuda a comprender qué hace cada código en la aplicación. Por ejemplo, ayuda a proporcionar una visión general clara de lo que hace cada variable, qué función específica en el proyecto es, si tiene un parámetro o un tipo de retorno, y qué efectos tiene en el código, p. B. cuando los detalles están bien documentados. Imagina que tienes la oportunidad de trabajar en un gran proyecto con millones de piezas de código. Usted es responsable de corregir cualquier error en esta sección. Puede encontrar la línea de código donde ocurrió el error y el error fue causado por las dos funciones llamadas. Luego navegue hasta ese código de función después de pasar por cada línea de código donde encuentre que un modificador de acceso está causando el problema. Como resultado, el desarrollador tiene que pasar por una gran cantidad de código y todos deben comprender las conexiones entre los códigos para abordar un problema. Lidiar con un error en un proyecto más grande de esta manera es claramente un dolor de cabeza para los desarrolladores, especialmente para los novatos. Una buena documentación ayuda aquí. La documentación del código se usa típicamente Comprender qué variables, clases, objetos, funciones, etc. se utilizan en la aplicación y cuál es su propósito, y proporcionar información sobre si tiene parámetros, destinatarios o enlaces externos.Una vez que obtiene suficiente información sobre el código, se vuelve fácil trabajar en el código, lo que finalmente condujo a una Reduciendo el tiempo que lleva resolver e implementar una solución en la aplicación.pero siempre existen los dos peores escenarios al documentar

Contenidos

Documentación perezosa

La documentación perezosa es el documento con menos información. Si un documento no le brinda suficiente información sobre la funcionalidad, tiene un formato perezoso. Lo cual es inútil porque no tiene valor hacer que el código sea comprensible.

Documentación OverInfo

Parte de la documentación brinda más información de la necesaria, lo que lleva a un uso poco claro del código y crea confusión sobre el código. Dedicar un tiempo fructífero a la lectura de la documentación es importante para comprender el uso adecuado del código, pero ¿qué sucede si se necesita el doble de esfuerzo para comprender el código? o la sobrecarga de información causa demasiada dificultad para procesar el código para un desarrollador o incluso conduce a un uso poco claro, esto se hace en una documentación con exceso de información

  • debería ser comprensible
  • Debe ser preciso y actualizado.
  • simple y conciso
  • Formato correcto
  • El documento siempre debe dar en el blanco.
  • Debe describir correctamente cada funcionalidad
  • Debe documentar adecuadamente sus parámetros, enlaces y destinatarios, si los hubiere.

En Java, Javadoc se usa para documentar código Java. Antes de Dokka, no había una herramienta adecuada para documentar Kotlin. Dokka es una herramienta de documentación similar a Javadoc. La principal diferencia entre Javadoc y Dokka es que Dokka es compatible con la documentación de Kotlin y Java. La documentación de Dokka es posible con KDoc.

Kdoc

KDoc es el Idioma Se utiliza para documentar el código Kotlin. Los comentarios adecuados son necesarios para crear una buena documentación. KDoc también ayuda a comentar usando etiquetas de bloque y rebajas. Básicamente es un complemento utilizado en Android Studio que ayuda con la documentación. Podemos usar KDoc de la siguiente manera

  • Los comentarios de KDoc comenzaban con /** como etiqueta de apertura y terminaban con la etiqueta de cierre */
  • KDoc admite etiquetas de bloque, así como Markdown en línea y HTML para proporcionar información adicional sobre los elementos incrustados con el símbolo @

etiquetas de bloque

  • @receiver: extensión del receptor de documentos
  • @param: documenta propiedades de clases o funciones con nombre y descripción
  • @ver: los documentos se vinculan a una clase o función específica

Rebaja en línea

  • #h1, ##h2, []> etc. Las etiquetas son compatibles

Etiquetas HTML, , , etc. También se pueden usar etiquetas

Lea más sobre las guías de Markdown para familiarizarse con ellas

dokka

Es una herramienta utilizada para crear documentación. La documentación generada puede ser esencialmente se muestra en formatos que incluyen HTML, marcado y Javadoc estándar. Dokka es compatible con la documentación de Java y Kotlin. Genera un documento de Kotlin cuando se incrusta en el archivo de Kotlin usando KDoc y genera Javadoc cuando se anota con comentarios de Javadoc.

1. Implementar dependencias a nivel de proyecto en build.gradle

complementos { id ‘org.jetbrains.dokka’ versión ‘1.7.0’ aplicar falso}

2. Implementar dependencias a nivel de módulo en build.gradle

Complementos { id ‘org.jetbrains.dokka’ }

  • Si tiene varios módulos, agréguelos también
  • proyecto de sincronización

Después de una compilación exitosa, siga los pasos a continuación

3. Creación de documentos

abre eso Terminal opción en Android Studio e ingrese lo siguiente

  • Para crear un documento para el módulo Ingrese el script en la terminal

./gradlew dokkaHtml

  • Cómo crear un documento para módulo múltiple ingresa de la siguiente manera

./gradlew dokkaHtmlMultiModuleUna vez que se complete el proceso, puede ver el documento generado dentro build/dokka cambiando el tipo de vista de Android a Project. Aquí hay un ejemplo de compilación de Dokka generada en un proyecto de código abierto control deslizante.Vista del proyecto desde el proyecto sliderzY al hacer clic en el index.html y abrir el navegador podemos ver la documentación del código generado HTML formato que es formato estandar.Documentación por Sliderz

El Dokka también es compatible con otros formatos, incluidos Javadoc, gfm y Jekyll.

Pero si no pusimos un comentario de kdoc, habrá un documento HTML vacío. Para hacer esto, necesitamos incluir el comentario de KDoc. Comentarios normales con // comentario, /* comentario*/,

Kdoc comentando

/** y presiona Enter**/fun foo(parámetro){ }

descansar

  • La documentación de código más explicativa solo es posible eligiendo convenciones de nomenclatura apropiadas y nombres de variables bien definidos.
  • Puede proporcionar detalles adicionales para que se muestren en la documentación.

/*** Realiza una operación complicada.** @param remoto Si es verdadero, realiza la operación de forma remota * @regresar El resultado de ejecutar la operación **/fun foo(remote: Boolean): Result { … }

Se puede ampliar aún más si se implementan en el código un constructor, un lanzamiento de excepción, etc. Puede ver las otras etiquetas de bloque utilizadas en la documentación oficial de KDoc. https://kotlinlang.org/docs/kotlin-doc .html#module-and-package-documentation Esta es una guía rápida sobre cómo implementar Dokka en Android Studio. Puede verificar la sintaxis adicional en el enlace de arriba. Todo este blog trata sobre información básica de documentación. Espero que lo hayas disfrutado y lo hayas encontrado útil en tu viaje de desarrollo. Eso es todo por hoy. Que tengas un buen día 👋👋👋👋

Deja una respuesta

Tu dirección de correo electrónico no será publicada.