Wunderschöne APIs

written by Martin Häcker on

Dokumentation.

Den vergleich zwischen Dokumentation und dem Austausch von Körperflüssigkeiten spare ich mir jetzt. Wahr ist er aber trotzdem.

Vergleicht man die Python und die Cocoa Dokumentation dann fällt bei Cocoa recht schnell auf das es keine klare Trennung gibt in High level Dokumentation und Klassenspezifische Dokumentation während das bei Python gemischt ist.

Dazu kommt das bei Python oft die high level Beispiele fehlen und es von der Referenz-Dokumentation keinen Link auf die komplette Listung der Methoden eines Objekts gibt.

Zwar kann man dann in Python oft auf den interpreter zurückgreifen und sich von dort aus noch mehr informationen über ein Objekt holen - das ist aber ganz schön aufwendig.

High Level Dokumentation: Cocoa++, Python--

Wenn es um die Klassenbasierte Doku geht hat Cocoa auch eindeutig die Nase vorne. Alle Methoden sind immer nach Topics geordnet. NSArray zum Beispiel startet mit einer Liste der Fakten über die Klasse (in welchem file definiert, ab welcher Version des Frameworks verfügbar, welche High-Level Guides gehören dazu) und fährt dann erst einmal mit einem Überblick über den Zweck der Klasse fort der auch gleichzeitig die wichtigsten Methoden der Klasse erklärt.

Danach kommt immer der Guide was man beachten muss wenn man eine Subklasse davon anlegen will. (Was erfordern kann dass man ein bestimmtes set von Methoden immer gleichzeitig überschreiben muss, da in Cococa gerne Class Clusters eingesetzt werden - ein Konzept das ich in Python leider noch gar nicht gefunden habe.

Dann kommt der für die tägliche Arbeit für mich wichtigste Teil der Dokumentation: Tasks. Hier sind alle Methoden des Objekts nach den Aufgaben sortiert die man mit ihnen erledigt.

Creating an Array, Initializing an Array, Querying an Array, Comparing, Sorting, ...

So findet man schnellstens heraus was das Objekt anbietet für das was man tun möchte.

Ergo: Dokumentation in Python ist ganz schön mies - in Trac fehlt sie sogar ganz :/