So halten Sie Codebeispiele in Javadocs auf dem neuesten Stand

Ich arbeite an einer kleinen Bibliothek, die Implementierungen grundlegender, bekannter String-Metriken bereitstellt. Meistens für meine eigene Ausbildung. Die Entwicklung findet also immer dann statt, wenn ich etwas Freizeit habe.

Aus diesem Grund habe ich die meisten Prozesse automatisiert, sodass ich eine Version so oft veröffentlichen kann, wie ich ohne großen Aufwand daran arbeite. Die Pflege des Java-Dokuments ist jedoch immer noch eine Belastung, da es Beispiele enthält.

Während sich die API weiterentwickelt, muss ich jedes Beispiel immer wieder manuell überprüfen. Gibt es einen besseren Weg, dies zu tun?

Ich habe überlegt, die Dokumentation und Beispiele in ein separates Projekt (z. B. Caliper Tutorial ) zu verschieben, damit es zusammen mit dem regulären Code neu faktorisiert und kompiliert werden kann. Dadurch wird die Dokumentation jedoch von der Klasse entfernt, um die es geht.

Also ja. Ich möchte meinen Kuchen haben und ihn auch essen. : D.

 * <h2>Tokenization</h2>
 * 
 * Tokenization cuts up a string into tokens e.g.
 * <code>chilperic ii son of childeric ii</code> is tokenized into
 * <code>[chilperic, ii, son, of,
 * childeric, ii]</code>. Tokenization can also be done repeatedly by tokenizing
 * the individual tokens e.g.
 * <code>[ch,hi,il,il,lp,pe,er,ri,ic, ii, so,on, of, ch,hi,il,ld,de,er,ri,ic, ii]</code>
 * <p>
 * 
 * <pre>
 * <code>
 * {@code
 *  return new StringMetricBuilder()
 *          .with(new SimonWhite<String>())
 *          .tokenize(new Whitespace())
 *          .tokenize(new QGram(2))
 *          .build();
 * }
 * </code>
 * </pre>
 * 
 * <p>

Wenn das oben genannte zu abstrakt ist. Dies ist ein Beispiel für eine Dokumentation. Derzeit füge ich statische Konstruktoren hinzu, wie von Effective Java empfohlen, z. B. Tokenizers.createQGram(2)während die Konstruktormethode abgeschrieben wird. Jedes Mal, wenn ich so etwas mache, muss ich den obigen Beispielcode aktualisieren und prüfen, ob er noch funktioniert.

Dies beantwortet Ihre Frage möglicherweise nicht - je nachdem, wie wichtig es ist, diese Beispiele in Ihrer Dokumentation zu haben.

Vielleicht könnten Sie einen anderen Blickwinkel einnehmen: Geben Sie Beispiele in Ihren JUnit-Tests an. (Vielleicht sogar ein Paket wie com.examples) Das Problem mit Code in Kommentaren ist, dass Ihre IDE ihn größtenteils ignoriert. Ihre IDE überprüft den Code jedoch in Ihren JUnit-Tests. Auf diese Weise stellen Sie sicher, dass die Codebeispiele korrekt sind. Die Tests werden entweder nicht kompiliert oder schlagen einfach fehl, wenn Sie sie nicht aktualisiert haben.

Ich bin kein Assistent von Javadocs, aber es gibt möglicherweise eine Möglichkeit, die Dokumentation Ihrer Quelldatei mit der JUnit-Datei mit dem darin enthaltenen Beispielcode zu verknüpfen. Ich würde wirklich nicht wissen, wo ich damit anfangen soll. Ein flüchtiges Googeln zeigte mir das @seeEtikett . Ich habe es in einem Projekt getestet, aber nicht in einem tatsächlichen Javadoc getestet, nachdem es generiert wurde.

Dies würde definitiv ein wenig Recherche im Voraus erfordern, aber ich denke wirklich, dass Sie auf lange Sicht besser dran wären, wenn Ihre Codebeispiele tatsächlich kompiliert würden.

Als Stretch-Ziel können Sie beim Ausführen Ihrer JUnit-Beispiele auch die Codeabdeckung erweitern. Auf diese Weise wissen Sie auf einen Blick, wie viel Ihrer Codebasis von Ihren Beispielen abgedeckt wird.