Questions & Answers

lars_wingbermue
I'm new here

Optimierung der Java-API-Dokumentation

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?

10 Replies
StefanSchulz
I'm new here

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 Kudos

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).ReferenceEntry.png

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 Smiley Wink

Viele GrรผรŸe

Marcel

0 Kudos

Vielen Dank fรผr den Hinweis.

GruรŸ

Stefan

0 Kudos

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. Smiley Wink

Beste GrรผรŸe

Stefan

0 Kudos

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 Smiley Wink

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. Smiley Happy Wie gesagt, nur beispielhaft ...

Viele GrรผรŸe

Marcel

0 Kudos

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 Kudos

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

Peter
0 Kudos

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 Kudos

Type a product name