- Mark as New
- Bookmark
- Subscribe
- Mute
- Subscribe to RSS Feed
- Permalink
- Report Inappropriate Content
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?
- Labels:
-
Developers
- Tags:
- api
- dokumentation
- java
- Mark as New
- Bookmark
- Subscribe
- Mute
- Subscribe to RSS Feed
- Permalink
- Report Inappropriate Content
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
- Mark as New
- Bookmark
- Subscribe
- Mute
- Subscribe to RSS Feed
- Permalink
- Report Inappropriate Content
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).
- Mark as New
- Bookmark
- Subscribe
- Mute
- Subscribe to RSS Feed
- Permalink
- Report Inappropriate Content
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
Viele Grรผรe
Marcel
- Mark as New
- Bookmark
- Subscribe
- Mute
- Subscribe to RSS Feed
- Permalink
- Report Inappropriate Content
Vielen Dank fรผr den Hinweis.
Gruร
Stefan
- Mark as New
- Bookmark
- Subscribe
- Mute
- Subscribe to RSS Feed
- Permalink
- Report Inappropriate Content
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.
Beste Grรผรe
Stefan
- Mark as New
- Bookmark
- Subscribe
- Mute
- Subscribe to RSS Feed
- Permalink
- Report Inappropriate Content
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
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. Wie gesagt, nur beispielhaft ...
Viele Grรผรe
Marcel
- Mark as New
- Bookmark
- Subscribe
- Mute
- Subscribe to RSS Feed
- Permalink
- Report Inappropriate Content
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
- Mark as New
- Bookmark
- Subscribe
- Mute
- Subscribe to RSS Feed
- Permalink
- Report Inappropriate Content
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
- Mark as New
- Bookmark
- Subscribe
- Mute
- Subscribe to RSS Feed
- Permalink
- Report Inappropriate Content
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

