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