Dokumentationslinks mit Sensei verwenden

Eine der Schwierigkeiten beim Erlernen einer neuen Bibliothek oder beim Teilen vereinbarter Praktiken innerhalb unseres Teams besteht in der Dokumentation und der Erstellung von Beispielen.

Sehr oft erstellen wir kleine Beispielprojekte, haben diese jedoch nicht geöffnet, wenn wir mit dem eigentlichen Code arbeiten.

Ich habe oft gedacht, es wäre großartig, unsere Beispiele oder Online-Beispiele verlinken zu können und bei Bedarf eine URL für weitere Erklärungen aufrufen zu können.

In Java haben wir JavaDoc-Kommentare, die eine see-Annotation enthalten können:

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

Solche JavaDocs in Bibliotheken von Drittanbietern sind eine große Hilfe, da wir die Quick-Documentation-Funktion in IntelliJ nutzen können, um Zugriff auf detailliertere Beispiele zu erhalten.

Wir wissen jedoch alle, dass Kommentare nicht so oft aktualisiert werden wie der Code, und die Pflege der Webpräsenz ist oft von der Bibliotheksverwaltung entkoppelt und wird manchmal von einem ganz anderen Team durchgeführt.

Wie Sensei hilft

Sensei bietet die Möglichkeit, Bibliotheksannotationen und -methoden abzugleichen, um Links zu ausführlicher Dokumentation in einem Wiki oder auf einer Tutorial-Seite von Drittanbietern bereitzustellen.

Als Beispiel verwende ich die @Test Annotation von JUnit.

Das JavaDoc ist sehr detailliert und die Quick-Documentation-Ansicht erklärt, wie die Annotation verwendet wird.

Aber die offizielle Dokumentation auf der Website ist oft leichter zu lesen und enthält mehr Beispiele.

Wenn ein Team beginnt, eine Bibliothek zu erlernen, kann eine Zusammenstellung empfohlener Tutorials sehr nützlich sein.

Sensei verfügt über eine goto Aktion, mit der wir eine URL öffnen können. So können wir auf externe Seiten und Beispiele für Dokumentationen verlinken, die wir als Team für nützlich halten.

Implementierung der Goto-URL

Um dies zu implementieren, würde ich eine Suche erstellen, die mit der @Test-Annotation von JUnit übereinstimmt.

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

Und dann würde ich für jede der URLs, die ich nützlich finde, Goto-Aktionen hinzufügen.

z. B.

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

Das folgende Beispiel würde eine einzelne Aktion erstellen, JUnit-Annotationen (lernen) die beide URLs gleichzeitig in einem Browser öffnet.

availableFixes:
- name: "Mehr über JUnit-Annotationen erfahren"
  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"

Und wenn ich es in IntelliJ mit Alt+Eingabetaste aktiviere, sehe ich das Kontextmenü, in dem ich auswählen kann, zur Dokumentation zu springen.

Mehrere Aktionen

Ich könnte mich für mehrere Aktionen entscheiden, damit jede URL oder jedes Tutorial eine eigene Option im Alt+Eingabetaste Quick-Fix-Menü erhält.

Für die @Parameterized-Annotation möchte ich beispielsweise auf die offizielle Dokumentation und eine Reihe von Online-Beispielcodes verlinken.

• 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

Ich würde einfach ein Rezept erstellen, das nach der Annotation sucht:

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

Und auf die Seiten verlinken, die ich als nützlich identifiziert habe:

availableFixes:
- name: "JUnit-Annotationen (lernen)"
  actions:
  - goto:
      type: "URL"
      value: "https://junit.org/junit5/docs/current/user-guide/#writing-tests-annotations"
- name: "Was ist ein JUnit-Test? (lernen)"
  actions:
  - goto:
      type: "URL"
      value: "https://junit.org/junit5/docs/current/user-guide/#writing-tests-classes-and-methods"

Beide Links würden dann im Pop-up-Dialog erscheinen.

Wer profitiert davon?

Ich hätte dies beim Erlernen und Verwenden von Bibliotheken nützlich gefunden, insbesondere wenn ich Teams leite und ihnen bei der Einführung einer neuen Bibliothek helfe.

Dies könnte auch Teams zugutekommen, die Bibliotheken erstellen, indem sie einen Standardsatz an Dokumentationsrezepten erstellen, um Benutzer bei der Einführung der Bibliothek oder neuer Funktionen zu unterstützen.

Dies wäre besonders nützlich, wenn die Wartung des Codes und die Pflege der Dokumentation von verschiedenen Teams durchgeführt werden.

Sie können Sensei direkt in IntelliJ über `Einstellungen > Plugins` installieren (suchen Sie einfach nach "sensei secure code").

Der gesamte Code für diesen Blogbeitrag befindet sich auf Github im Modul junitexamples unter https://github.com/SecureCodeWarrior/sensei-blog-examples