Utiliser des liens de documentation avec Sensei

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

Nous créons très souvent de petits projets d'exemple, mais nous ne les gardons pas sous les yeux lorsque nous travaillons sur le code réel.

J'ai souvent pensé qu'il serait formidable de pouvoir créer des liens vers nos exemples ou des exemples en ligne, et d'accéder à une URL pour obtenir des explications supplémentaires si nécessaire.

En Java, nous disposons des commentaires JavaDoc, qui peuvent inclure une annotation « see » :

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

Une telle JavaDoc dans des bibliothèques tierces est une aide précieuse, car nous pouvons utiliser la fonctionnalité de documentation rapide d'IntelliJ pour accéder à des exemples plus détaillés.

Cependant, nous savons tous que les commentaires ne sont pas mis à jour aussi souvent que le code, et que la maintenance de la présence en ligne est souvent déconnectée de celle de la bibliothèque, étant parfois assurée par une équipe totalement différente.

Comment Sensei vous aide

Sensei permet de faire correspondre des annotations et des méthodes de bibliothèque afin de fournir des liens vers une documentation détaillée sur un wiki ou un site de tutoriels tiers.

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

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

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

Lorsqu'une équipe commence à apprendre une bibliothèque, disposer d'une série de tutoriels recommandés peut s'avérer très utile.

Sensei dispose d'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, jugeons utiles.

Implémentation de l'action Goto URL

Pour implémenter cela, je créerais une recherche qui correspond à 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.

ex.

• 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éerait une seule action Annotations JUnit (apprendre) qui ouvrirait les deux URL dans un navigateur simultanément.

availableFixes:
- name: "En savoir plus sur les annotations 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"

Et lorsque je l'active dans IntelliJ avec Alt+Entrée 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 dispose de sa propre option dans le menu contextuel de correction rapide alt+entrée.

Par exemple, pour l'annotation @Parameterized, je pourrais vouloir créer un lien vers la documentation officielle et vers 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 recherche l'annotation :

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

Et qui renvoie vers les sites que j'ai identifiés comme utiles :

availableFixes:
- name: "Annotations JUnit (apprendre)"
  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"
      value: "https://junit.org/junit5/docs/current/user-guide/#writing-tests-classes-and-methods"

Les deux liens apparaîtraient alors dans la boîte de dialogue contextuelle.

Qui en bénéficierait ?

J'aurais trouvé cela utile lors de l'utilisation et de l'apprentissage de 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 créant des bibliothèques, en créant un ensemble standard de recettes de documentation pour aider à guider les utilisateurs dans l'adoption de la bibliothèque ou de ses nouvelles fonctionnalités.

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

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

Tout le code de cet article de blog se trouve sur Github dans le module junitexamples à l'adresse https://github.com/SecureCodeWarrior/sensei-blog-examples