Verwendung von Dokumentationsverknüpfungen mit Sensei

Eine der Schwierigkeiten beim Erlernen einer neuen Bibliothek oder beim Austausch vereinbarter Praktiken innerhalb unseres Teams ist die Dokumentation und Erstellung von Beispielen.

Sehr oft erstellen wir kleine Beispielprojekte, aber wir haben sie nicht offen, wenn wir mit dem eigentlichen Code arbeiten.

Ich habe schon oft darüber nachgedacht, dass es toll wäre, die Möglichkeit zu haben, auf unsere Beispiele oder Online-Beispiele zu verlinken und bei Bedarf zu einer URL für weitere Erklärungen gehen zu können.

Bei Java gibt es JavaDoc-Kommentare, die eine see-Annotation haben können:

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

JavaDoc wie dieses in Bibliotheken von Drittanbietern ist eine große Hilfe, weil wir die Schnelldokumentationsfunktion in IntelliJ nutzen können, um Zugang zu detaillierteren Beispielen zu haben.

Aber wir alle wissen, dass Kommentare nicht so oft aktualisiert werden wie der Code, und die Pflege der Webpräsenz ist oft von der Pflege der Bibliothek abgekoppelt und wird manchmal von einem ganz anderen Team durchgeführt.

Wie Sensei hilft

Sensei bietet die Möglichkeit, auf Bibliothekskommentare und -methoden abzustimmen, um Links zur Langform-Dokumentation auf einem Wiki oder einer Tutorial-Site eines Drittanbieters bereitzustellen.

Als Beispiel verwende ich die @Test-Annotation von JUnit.

Die JavaDoc ist sehr detailliert, und in der Ansicht "Quick Documentation" wird erklärt, wie Sie die Anmerkung verwenden.

Aber die offizielle Dokumentation auf der Website ist oft einfacher zu lesen und hat mehr Beispiele.

Wenn ein Team mit dem Erlernen einer Bibliothek beginnt, kann es sehr nützlich sein, eine Reihe von empfohlenen Tutorials zu haben.

Sensei hat eine "goto" -Aktion, mit der wir eine URL öffnen können. Damit können wir auf externe Seiten und Beispiele für Dokumentationen verweisen, die wir als Team für nützlich halten.

Implementieren 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 für nützlich halte, 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 Action JUnit Annotations (learn) erstellen, die beide URLs gleichzeitig in einem Browser öffnen würde.

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"

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

Mehrere Aktionen

Ich könnte mich für mehrere Aktionen entscheiden, so dass jede URL oder jedes Tutorial eine eigene Option im Einblendmenü " Alt+Eingabe Schnellreparatur" hat.

Zum Beispiel könnte ich für die @Parameterized-Annotation einen Link auf die offizielle Dokumentation und einen Satz Online-Beispielcode setzen wollen.

• 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 Anmerkung sucht:

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

Und Links zu den Seiten, die ich als nützlich identifiziert habe:

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

Beide Links würden dann im Popup-Dialog erscheinen.

Wer würde davon profitieren?

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

Dies könnte auch den Teams zugute kommen, die Bibliotheken erstellen, indem sie einen Standardsatz von Dokumentationsrezepten erstellen, die den Benutzern bei der Einführung der Bibliothek oder neuer Funktionen in der Bibliothek helfen.

Dies ist vor allem dann sinnvoll, wenn die Pflege des Codes und die Pflege der Dokumentation von verschiedenen Teams durchgeführt wird.

Sie können Sensei aus IntelliJ heraus über `Präferenzen > Plugins` installieren (suchen Sie einfach nach "sensei secure code").

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