Optimierung der Java-API-Dokumentation
Author: lars_wingbermue
Publication Date: 12/2/2014 8:45
Ich erhalte von unseren Java-Entwicklern immer wieder die Rückmeldung, dass die API-Dokumentation der FS-Schnittstelle sehr schlecht beschrieben ist. Um das Thema einmal hier zu platzieren und ggf. auf Feedback von anderen Nutzern einzuholen, eröffne ich einmal eine Diskussion dazu.
Ein Vorschlag wäre es sich die Java-Dokumentation selber als Vorbild zu nehmen.
Ein extremes Beispiel dort ist die String Klasse. Dort ist jede Methode der Klasse exakt beschrieben:
http://docs.oracle.com/javase/7/docs/api/java/lang/String.html
Und als Übersicht die Package Summary: http://docs.oracle.com/javase/7/docs/api/java/lang/package-summary.html
Wie man eine gute API DOC schreibt ist hier beschrieben: http://www.oracle.com/technetwork/articles/java/index-137868.html
Wie wird das bei anderen Nutzern gesehen?
Gibt es dort die selben Probleme bzw. Wünsche?
Wie gehen Sie bei der Entwicklung der Module und Anwendungen vor um das Problem zu minimieren?
Tags: api, dokumentation, java
-
Author: StefanSchulz - 12/2/2014 12:36
Hallo,
vielen Dank für die Rückmeldung. Natürlich sind wir immer daran interessiert, die Dokumentation insbesondere für Entwickler zu verbessern. Ein generisches "sehr schlecht beschrieben" hilft uns jedoch nicht wirklich weiter. Die API ist mittlerweile sehr umfangreich und eine vollständige Überarbeitung wäre alleine aus Zeitgründen weder machbar noch für den aktuellen Stand vor Ort hilfreich. Schöner wäre es, konkrete Problempunkte genannt zu bekommen, die dann möglichst zeitnah umgesetzt werden könnten.
Beste Grüße
Stefan
0 -
Author: sguener - 12/2/2014 16:30
Mir ist gestern ein Fehler in der Access-API Doc (Interface: ReferenceEntry) aufgefallen: [ODFS-URL]/odfs/access/de/espirit/firstspirit/access/ReferenceEntry.html -> Die Formatierung ist "kaputt" (s. Screenshot).
0 -
Author: MarsDD - 12/2/2014 16:35
Hallo,
ich denke, das lieber ein Satz mehr zu einer Methode statt einer zu wenig damit gemeint ist.
Dem wäre ich auch nicht abgeneigt :smileywink:
Viele Grüße
Marcel
0 -
Author: StefanSchulz - 12/3/2014 6:37
Vielen Dank für den Hinweis.
Gruß
Stefan
0 -
Author: StefanSchulz - 12/3/2014 6:39
Hallo Marcel,
das kann man sich natürlich vornehmen, hilft aber nicht abzuschätzen, ob der "Satz mehr" nun ausreicht oder nicht. Dokumentation ist kein einfaches Thema, da die Beschreibenden sicherlich sagen werden, dass die Ausführungen "doch klar" sind. :smileywink:
Beste Grüße
Stefan
0 -
Author: MarsDD - 12/3/2014 7:06
Hallo Stefan,
das stimmt wohl, alle wird man nicht unter einen Hut bekommen. Denke ich jedoch an meine Anfänge mit dem Umgang der API, so war es für mich schon recht schwierig einen Überblick/Einstiegspunkt zu finden. Jetzt wo ich ungefähr weiss, wie was zu machen ist, welche Dinge miteinander zu verstehen sind und durch die expertise von meinen Kollegen wird der Raum immer heller :smileywink:
Schauen wir uns beispielhaft das Interface TemplateRootStore an. Die Funktionsnamen sind schon selbstsprechend, ohne jeden Zweifel - jedoch fehlt bei allen Funktionen wenigstens mal ein Satz, was die Funktion macht. :smileyhappy: Wie gesagt, nur beispielhaft ...
Viele Grüße
Marcel
0 -
Author: StefanSchulz - 12/3/2014 7:20
Moin Marcel,
du hast sicherlich Recht. "Nicht vorhanden" ist schlecht. Dieses generelle Problem kann man natürlich auf die Liste setzen, ist aber extrem umfangreich und sicherlich nicht zeitnah zu lösen. Dein Beispiel ist übrigens seit mindestens 2008 so in der API vorhanden und anscheinend hat es bislang niemanden stark genug gezwickt, um eine (konkrete) Besserung einzufordern. Ist natürlich auch nicht obligatorisch und eher unser Problem, aber eben schwer nachzuhalten.
Besten Dank und Gruß
Stefan
0 -
Author: Peter_Jodeleit - 12/3/2014 7:52
Sahin Güner schrieb:
Mir ist gestern ein Fehler in der Access-API Doc (Interface: ReferenceEntry) aufgefallen: [http://www.e-spirit.com/odfs51/access/de/espirit/firstspirit/access/ReferenceEntry.html] -> Die Formatierung ist "kaputt" (s. Screenshot).
Danke für den Hinweis, da fehlte eine schließendes Tag. Interne Id: #77317
0 -
Author: MarsDD - 1/7/2015 13:46
Hallo zusammen,
ich habe eben noch einen Fehler entdeckt:
Wenn ich in der API unter UserService auf den Returnwert SecurityManager (getSecurityManager) klicke bekomme ich einen 404er
Viele Grüße und eine gesundes Neues =)
Marcel
0
Vous devez vous connecter pour laisser un commentaire.
Commentaires
9 commentaires