Utiliser les liens de documentation avec Sensei

L'une des difficultés liées à l'apprentissage d'une nouvelle bibliothèque ou au partage de pratiques communes au sein de notre équipe réside dans la documentation et la création d'exemples.

Très souvent, nous créons de petits projets d'exemple, mais nous ne les ouvrons pas lorsque nous travaillons avec le code réel.

J'ai souvent pensé qu'il serait formidable de pouvoir créer un lien vers nos exemples ou vers des exemples en ligne et de pouvoir accéder à une URL pour plus d'explications lorsque cela est nécessaire.

Avec Java, nous avons des commentaires JavaDoc, qui peuvent avoir une annotation see :

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

Les JavaDocs de ce type dans les bibliothèques tierces sont d'une grande aide car nous pouvons utiliser la fonctionnalité de documentation rapide dans IntelliJ pour avoir accès à des exemples plus détaillés.

Mais nous savons tous que les commentaires ne sont pas mis à jour aussi souvent que le code, et que la maintenance de la présence sur le web est souvent déconnectée de la maintenance de la bibliothèque et parfois réalisée par une équipe complètement différente.

Comment Sensei vous aide

Sensei permet de faire correspondre les annotations de la bibliothèque et les méthodes pour fournir des liens vers une documentation longue sur un wiki ou un site de tutorat tiers.

A titre d'exemple, j'utilise l'annotation @Test de JUnit.

La JavaDoc est très détaillée et la vue Documentation rapide explique comment utiliser l'annotation.

Mais la documentation officielle sur le site web est souvent plus facile à lire et contient plus d'exemples.

Lorsqu'une équipe commence à apprendre une bibliothèque, il peut être très utile de disposer d'un ensemble de tutoriels recommandés.

Sensei possède une action goto que nous pouvons utiliser pour ouvrir une URL, ce qui nous permet de créer des liens vers des sites externes et des exemples de documentation que nous, en tant qu'équipe, trouvons utiles.

Mise en œuvre de l'URL Goto

Pour mettre cela en œuvre, je créerais une recherche qui correspondrait à l'annotation @Test de Junit.

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

Ensuite, j'ajouterais des actions "goto" pour chacune des URL que je trouve utiles.

par exemple

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

L'exemple ci-dessous crée une seule action JUnit Annotations (learn) qui ouvre les deux URL dans un navigateur en même temps.

availableFixes :
- name : "Learn about JUnit Annotations"
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"

Et lorsque je l'active dans IntelliJ avec Alt+Enter , je vois le menu contextuel que je peux sélectionner pour accéder à la documentation.

Actions multiples

Je pourrais choisir d'avoir plusieurs actions afin que chaque URL ou tutoriel ait sa propre option dans le menu contextuel de la correction rapide alt+enter.

Par exemple, pour l'annotation @Parameterized, je pourrais vouloir créer un lien vers la documentation officielle et un ensemble d'exemples de code en ligne.

• 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

Je créerais simplement une recette qui rechercherait l'annotation :

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

Et des liens vers les sites que j'ai identifiés comme étant utiles :

availableFixes :
- name : "JUnit Annotations (learn)"
actions :
- goto :
type : "URL"
value : "https://junit.org/junit5/docs/current/user-guide/#writing-tests-annotations"
- name : "Qu'est-ce qu'un test JUnit ? (apprendre)"
actions :
- goto :
type : "URL"
valeur : "https://junit.org/junit5/docs/current/user-guide/#writing-tests-classes-and-methods"

Les deux liens apparaissent alors dans la boîte de dialogue.

Qui en bénéficierait ?

J'aurais trouvé cela utile pour l'utilisation et l'apprentissage des bibliothèques, en particulier lorsque je dirige des équipes et que je les aide à adopter une nouvelle bibliothèque.

Cela pourrait également profiter aux équipes qui créent des bibliothèques, en créant un ensemble standard de recettes de documentation pour aider les gens à adopter la bibliothèque ou de nouvelles fonctionnalités dans la bibliothèque.

Ceci est particulièrement utile si la maintenance du code et la maintenance de la documentation sont effectuées par des équipes différentes.

Vous pouvez installer Sensei depuis IntelliJ en utilisant `preferences > plugins` (recherchez simplement "sensei secure code").

Tout le code de ce billet se trouve sur Github dans le module junitexamples dans https://github.com/SecureCodeWarrior/sensei-blog-examples