Bei der Erstellung von API-Dokumentation besteht die Gefahr, dass relevante Informationen fehlen und irrelevante enthalten sind. Das Lesen dieser Art von Dokumentation ist aufwändig, u.U. nicht zielführend und kostet daher unnötig Zeit – und zwar für Autor und Leser. Dieser Vortrag diskutiert Ursachen dafür und zeigt, wie Lücken und irrelevante Aspekte in API-Dokumentation erkannt und vermieden werden können. Auf diese Weise kann die Pflege und Nutzung von API-Dokumentation trotz eines stressigen Projektalltags möglich werden.

1. Leichtgewichtige API-Dokumentation –
Ein Paradoxon?
Jan Christian Krause
Developer Conference Hamburg
07. Septmember 2012

2. Agenda
Motivation
Metaphern
Stand der Kunst: API-Dokumentation
API-Doku mit thematischen Rastern
iDocIt! – Ein Werkzeug zur API-Dokumentation
Beispiel: eBay Trading API
Zusammenfassung / Diskussion
Jan Christian Krause Seite 2

3. Motivation
Aus meinen Projekterfahrungen …
public interface CustomerService {
/**
* Finds the customers for the given lastname.
*
* @param lastname
* The lastname to look for
* @return The found customers
*
* @throws Exception
* In case of an error
*/
public List<Customer> findCustomerByName(
String lastname) throws Exception;
}
Jan Christian Krause Seite 3

4. Motivation
… resultierende Fragen
• Ist der Code die Dokumentation?
• Weshalb ist Dokumentieren so aufwändig?
Jan Christian Krause Seite 4

5. Metaphern
Vertrag
• Beschreibung der Dienstleistung der Operation
• Rechte und Pflichten des Konsumenten und
des Produzenten
Vertrag
Schnittstellenvertrag Implementierungsvertrag
(Spezifikation) (Dokumentation)
Jan Christian Krause Seite 5

6. Metaphern
Stille und Rauschen
• Stille:
Relevantes Charakteristikum der Operation,
das im Vertrag nicht erwähnt wird.
• Rauschen:
Überflüssiger Vertragsbestandteil
Jan Christian Krause Seite 6

7. Stand der Kunst: API-Dokumentation
Vertragsinhalte in der Praxis
• Vorgabe eines Rasters (z.B. Javadoc)
• Raster enthält öffentliche Signaturelemente
(z.B. Parameter, etc.), sowie Metadaten (z.B.
Autor, etc.)
• Natürlichsprachliche Kurzbeschreibung der
Operation
• Vor- und Nachbedingungen (selten)
Jan Christian Krause Seite 7

8. Stand der Kunst: API-Dokumentation
Gefahr von Stille
 Weitgehend standardisiertes und etabliertes
Vorgehensmodell
 Breite Werkzeugpalette verfügbar
 Seiteneffekte?
 Vollständigkeit der Beschreibungen?
 Spezifikationen (z.B. einer Rechenvorschrift)?
 Nicht sichtbare „Parameter“ (z.B. in
Konfigurationsdateien)?
Jan Christian Krause Seite 8

9. Stand der Kunst: API-Dokumentation
Gefahr von Rauschen (I)
Jan Christian Krause Seite 9

10. Stand der Kunst: API-Dokumentation
Gefahr von Rauschen (II)
Jan Christian Krause Seite 10

11. Stand der Kunst: API-Dokumentation
Gefahr von Rauschen (III)
Jan Christian Krause Seite 11

12. Stand der Kunst: API-Dokumentation
Gefahr von Rauschen (IV)
Jan Christian Krause Seite 12

13. API-Doku mit thematischen Rastern
Grundkonzept
• Operationsbezeichner enthalten ein Verb
• Das Verb hat eine Bedeutung.
• Die Bedeutung kann über Argumente
spezifiziert werden.
• Die Beschreibung der Argumente erfolgt an
der Operation (Lokalitätsprinzip).
Jan Christian Krause Seite 13

14. API-Doku mit thematischen Rastern
Beispiel für ein thematisches Raster
Searching Operations
Description: Represents operations which fetch one or
more objects from a defined source. The
returned objects are identied by a
specified set of criteria.
Verbs: find, get, search, look
Mandatory Roles: OBJECT, COMPARISON, SOURCE
Optional Roles: ORDERING, ALGORITHM
Jan Christian Krause Seite 14

15. API-Doku mit thematischen Rastern
Erkennung von Stille
Jan Christian Krause Seite 15

16. API-Doku mit thematischen Rastern
Erkennung von Rauschen (I)
Jan Christian Krause Seite 16

17. API-Doku mit thematischen Rastern
Erkennung von Rauschen (II)
Jan Christian Krause Seite 17

18. API-Doku mit thematischen Rastern
Erkennung von Rauschen (III)
Jan Christian Krause Seite 18

19. API-Doku mit thematischen Rastern
Detailliertes Beispiel
Searching Operation
A searching operation searches for one or many
OBJECTs at a SOURCE. The searched OBJECTs are
identified by one or many COMPARISONs or PRIMARY
KEYs. The number of found OBJECTs could be limited by
specifying a LIMIT. In case of many OBJECTs an
ORDERING defines their arrangement. The ALGORITHM
defines the way the OBJECTs are searched.
This category bases on the VerbNet classes Search-35.2
and obtain-13.5.2.
Jan Christian Krause Seite 19

20. API-Doku mit thematischen Rastern
Weitere Beispiele für thematische Raster
• Converting Operations
• Mathematical Operations
• Sending Operations
 AKRA arbeitet derzeit mit 22 thematischen
Rastern
Jan Christian Krause Seite 20

21. API-Doku mit thematischen Rastern
Zusammenfassung (I)
 Stille und Rauschen kann mit Hilfe
thematischer Raster vermieden werden
 Thematische Raster helfen ebenfalls bei der
Definition von Operationen einer Schnittstelle
(z.B. bei der Bestimmung der Parameter)
 Thematische Raster funktionieren ohne
Kenntnis von Quelltexten
Jan Christian Krause Seite 21

22. API-Doku mit thematischen Rastern
Zusammenfassung (II)
 Kardinalitäten thematischer Rollen nicht
ableitbar (z.B. Anzahl SOURCEs)
 Qualität der Bezeichner determiniert Qualität
der Unterstützung
 Thematische Raster müssen definiert werden
Jan Christian Krause Seite 22

23. iDocIt!
iDocIt! – Ein Werkzeug zur API-Dokumentation
• Editor zur Dokumentation
• Eclipse Plugin (Indigo 3.7)
• idocit.googlecode.com
• Unterstützt derzeit WSDL und Java
• Erweiterbar um weitere Programmier- /
Markupsprachen (als Plugins)
Jan Christian Krause Seite 23

24. Beispiel: Ebay Trading API
Kurzbeschreibung
• Ebay bietet Web Service zur Integration von
Ebay-Diensten in Anwendungen
• Analysiert wird die Operation
getFeedback(...)
• Ziel: Ermittlung von Stille und Rauschen
• Nutzung von iDocIt! als Analyse-Werkzeug
Jan Christian Krause Seite 24

25. Beispiel: Ebay Trading API
Ergebnisse – Stille:
• Sortierung der zurückgelieferten Bewertungen
ist nicht spezifiziert [them. Rolle ORDERING]
• Unterschiedliche Datenquellen (Sandbox-
und Produktivumgebung) sind nur
unzureichend dargestellt [them. Rolle
SOURCE]
• Berechnungsvorschrift für die Feedback-
Punktzahl ist nicht dokumentiert (findet sich
an anderer Stelle in der Ebay Online-Hilfe)
[them. Rolle FORMULA]
Jan Christian Krause Seite 25

26. Beispiel: Ebay Trading API
Ergebnisse – Rauschen:
• Vermeidung von Redundanz durch Nutzung
der Rolle PRIMARY KEY für ID-Felder (z.B.
FeedbackID)
• Durch Anwendung des Lokalitätsprinzips bzgl.
Felddokumentation lässt sich viel Rauschen
der Kategorie 2 einsparen, z.B. bei Feld
DetailLevel.
Jan Christian Krause Seite 26

27. Diskussion
Zusammenfassung
• Thematische Raster können helfen Stille und
Rauschen zu vermeiden
• Voraussetzung sind präzise gewählte Verben
in den Operationsbezeichnern
• Kardinalitäten thematischer Rollen sind nicht
ableitbar
Jan Christian Krause Seite 27

28. Diskussion
Ausblick
• Ausbau der Sammlung thematischer Raster
• Tiefere Integration von iDocIt! in die Eclipse-
Code-Editoren
• Studie zur Qualitätssteigerung durch
thematische Raster
Jan Christian Krause Seite 28

29. Diskussion
Diskussion
Vielen Dank für Ihre Aufmerksamkeit.
Haben Sie Anmerkungen, Fragen oder Kritik?
Jan Christian Krause Seite 29

30. Kontakt
Jan Christian Krause
Software-Entwickler
AKRA GmbH
Domstraße 17
20095 Hamburg
www.akra.de
Mail jan-christian.krause@akra.de
Büro +49 40 - 309 535 – 30
Twitter @iDocIt
Blog idocit.blogspot.de
Jan Christian Krause Seite 30