Uso de enlaces de documentación con Sensei

Una de las dificultades al aprender una nueva librería o compartir prácticas acordadas en el equipo es documentar y crear ejemplos.

A menudo creamos pequeños proyectos de ejemplo, pero no los tenemos abiertos cuando trabajamos con el código real.

Muchas veces he pensado que sería genial poder enlazar a nuestros ejemplos, o a ejemplos en línea, y acceder a una URL para obtener más explicaciones cuando sea necesario.

En Java, tenemos los comentarios JavaDoc, que pueden incluir una anotación see:

/**
 * @see <a href="https://junit.org/junit5/docs/current/user-guide/#writing-tests-annotations">Documentación de anotaciones de Junit 5</a>
 */

Un JavaDoc como este en librerías de terceros es de gran ayuda, ya que podemos usar la funcionalidad de Documentación Rápida en IntelliJ para acceder a ejemplos más detallados.

Pero todos sabemos que los comentarios no se actualizan tan a menudo como el código, y el mantenimiento de la presencia web suele estar desconectado del mantenimiento de la librería, siendo a veces realizado por un equipo completamente distinto.

Cómo ayuda Sensei

Sensei ofrece la capacidad de buscar coincidencias en anotaciones y métodos de librerías para proporcionar enlaces a documentación extensa en una wiki o en sitios de tutoriales de terceros.

Como ejemplo, estoy usando la anotación @Test de JUnit.

El JavaDoc es muy detallado y la vista de Documentación Rápida explica cómo utilizar la anotación.

Sin embargo, la documentación oficial en el sitio web suele ser más fácil de leer y contiene más ejemplos.

Cuando un equipo empieza a aprender una librería, contar con una serie de tutoriales recomendados puede ser muy útil.

Sensei cuenta con una acción goto que podemos usar para abrir una URL, lo que nos permite enlazar a sitios externos y ejemplos de documentación que, como equipo, consideramos útiles.

Implementación de la URL de destino

Para implementar esto, crearía una búsqueda que coincida con la anotación @Test de Junit.

search:
   annotation:
    owner:
      method: {}
    type: "org.junit.jupiter.api.Test"

Y luego añadiría acciones goto para cada una de las URLs que considero útiles.

p. ej.

• https://junit.org/junit5/docs/current/user-guide/#writing-tests-annotations
• https://junit.org/junit5/docs/current/user-guide/#writing-tests-classes-and-methods

El siguiente ejemplo crearía una única acción Anotaciones de JUnit (aprender) que abriría ambas URL en un navegador al mismo tiempo.

availableFixes:
- name: "Aprender sobre anotaciones de JUnit"
  actions:
  - goto:
      type: "URL"
      value: "https://junit.org/junit5/docs/current/user-guide/#writing-tests-annotations"=
  - goto:
      type: "URL"
      value: "https://junit.org/junit5/docs/current/user-guide/#writing-tests-classes-and-methods"

Y cuando la activo en IntelliJ con Alt+Enter veo el menú contextual que puedo seleccionar para saltar a la documentación.

Acciones múltiples

Podría optar por tener varias acciones para que cada URL o tutorial tenga su propia opción en el menú emergente de corrección rápida alt+enter.

Por ejemplo, para la anotación @Parameterized, podría querer enlazar a la documentación oficial y a un conjunto de ejemplos de código en línea.

• https://junit.org/junit5/docs/current/user-guide/#writing-tests-parameterized-tests
• https://github.com/eviltester/junitexamples/blob/master/src/test/java/parameterized/junit5/InitialExampleTest.java

Simplemente crearía una receta que busque la anotación:

search:
  annotation:
    owner:
      method: {}
    type: "org.junit.jupiter.params.ParameterizedTest"

Y enlaza a los sitios que identifiqué como útiles:

availableFixes:
- name: "Anotaciones de JUnit (aprender)"
  actions:
  - goto:
      type: "URL"
      value: "https://junit.org/junit5/docs/current/user-guide/#writing-tests-annotations"
- name: "¿Qué es una prueba de JUnit? (aprender)"
  actions:
  - goto:
      type: "URL"
      value: "https://junit.org/junit5/docs/current/user-guide/#writing-tests-classes-and-methods"

Ambos enlaces aparecerían entonces en el cuadro de diálogo emergente.

¿Quién se beneficiaría?

Me habría resultado útil al usar y aprender bibliotecas, especialmente al liderar equipos y ayudarles a adoptar una nueva biblioteca.

Esto también podría beneficiar a los equipos que crean bibliotecas, al crear un conjunto estándar de recetas de documentación para ayudar a guiar a las personas a través de la adopción de la biblioteca o de nuevas funciones en la misma.

Esto sería especialmente útil si el mantenimiento del código y el de la documentación son realizados por equipos diferentes.

Puedes instalar Sensei desde IntelliJ usando `preferences > plugins` (solo busca "sensei secure code").

Todo el código de esta entrada de blog está en Github en el módulo junitexamples en https://github.com/SecureCodeWarrior/sensei-blog-examples