iDocIt - Ein Assistent zur API-Dokumentation

Motivation
API-Dokumentation mit iDocIt!
Thematische Rollen und Raster f¨ur Web Services
Fallbeispiel
Fazit und Ausblick
iDocIt! - Ein Assistent zur API-Dokumentation
Jan Christian Krause
(AKRA GmbH)
NatS / WSV Oberseminar am 29.11.2011
Jan Christian Krause(AKRA GmbH) iDocIt! - Ein Assistent zur API-Dokumentation

Motivation
Fallbeispiel
Fazit und Ausblick
Agenda
Motivation
Metaphern Stille und Rauschen
Reminder: API-Dokumentation mit thematischen Rastern
iDocIt!
Vorbemerkungen
Thematische Rollen
Thematische Raster
Rollen und rasterbasierte Regeln
Fallbeispiel
Fazit und Ausblick

Motivation
Fallbeispiel
Fazit und Ausblick
Motivation - Cartoon I
F¨ur Quelle siehe letzte Folie

Motivation
Fallbeispiel
Fazit und Ausblick
Motivation - Cartoon II
F¨ur Quelle siehe letzte Folie

Motivation
Fallbeispiel
Fazit und Ausblick
Motivation - Fragen
Ist der Code die Dokumentation?
Worin besteht der Aufwand beim Dokumentieren?

Motivation
Fallbeispiel
Fazit und Ausblick
iDocIt!
Stille:
Stille: Relevanter Aspekt der Operation, der in der
Dokumentation nicht erwähnt wird
Rauschen:
Irrelevante, redundante, nicht aktuelle oder unnötig
ausführliche Dokumentation zu einem Aspekt der Operation
Stille und Rauschen erzeugen Aufwand bei der Erstellung und
bei der Konsultation von API-Dokumentation

Motivation
Fallbeispiel
Fazit und Ausblick
iDocIt!

Motivation
Fallbeispiel
Fazit und Ausblick
iDocIt!
iDocIt! - Ein Werkzeug zur API-Dokumentation
Entstanden in der Bachelor-Arbeit von Dirk Meier-Eickhoﬀ
(AKRA GmbH)
Eclipse Plugin (mind. Version 3.6)
Dynamische Hinweise auf Stille
Unterst¨utzt derzeit WSDL und Java (Erweiterbar um weitere
Programmier- und Markupsprachen (als Eclipse-Plugins))
Open Source-Projekt bei Google Code
(http://idocit.googlecode.com/)

Motivation
Fallbeispiel
Fazit und Ausblick
iDocIt!
Live-Demo von iDocIt!
Live-Demo

Motivation
Fallbeispiel
Fazit und Ausblick
Vorbemerkungen
Thematische Rollen
Thematische Raster
Vorbemerkungen
iDocIt! ben¨otigt thematische Rollen und Raster zur
Erkennung von Stille
Thematische Rollen und Raster wurden empirisch auf Basis
des seekda-Corpus ermittelt.
Beschreibung Wert
Anzahl Dienstanbieter 8.947
Anzahl WSDL-Beschreibungen 17.453
Anzahl Port Types 24.474
Anzahl Operationen 186.736

Motivation
Fallbeispiel
Fazit und Ausblick
Vorbemerkungen
Thematische Rollen
Thematische Raster
Vorgehensweise
1. Erstelle eine Liste aller Operationen und entferne Dubletten.
2. Mische die Liste zufällig und spalte sie in Pakete mit je 50
Operationen auf (Bezeichner, vollst. Input-, sowie
Output-Message und Faults).
3. Annotiere jedes Signaturelement jeder Operation mit einer
thematischen Rolle (definiere ggf. eine passende Rolle). Initial
werden die 14 von Girardi und Ibrahim identifzierten Rollen
vewendet.
4. Erfasse pro Paket die Anzahl der neu identifizierten
thematischen Rollen. Analysiere solange neue Pakete, bis der
Rollenzuwachs drei Mal 5% oder weniger beträgt.

Motivation
Fallbeispiel
Fazit und Ausblick
Vorbemerkungen
Thematische Rollen
Thematische Raster
S¨attigungskurve
Corpus Gr¨oße [Anzahl Pakete]
ThematischeRollen
0 1 2 3 4 5 6
10
20
30
40
50

Motivation
Fallbeispiel
Fazit und Ausblick
Vorbemerkungen
Thematische Rollen
Thematische Raster
Tabelle
Paket Rollen Neue Rollen Zuwachs [%] Ign. Operationen
0 14 14 0 0
1 31 17 1,21 1
2 37 6 0,19 2
3 42 5 0,14 1
4 44 2 0,05 2
5 44 0 0,00 2
6 45 1 0,02 5

Motivation
Fallbeispiel
Fazit und Ausblick
Vorbemerkungen
Thematische Rollen
Thematische Raster
Beispiele
ALGORITHM: Set of instructions how to perform the
ACTION.
FORMULA: Formula used to compute a value during the
ACTION.
OPERAND: Argument of a FORMULA.
ORDERING: The ordering of the returned OBJECTs.
LIMIT: The entity used to limit the ACTIONs space (e.g.
number of OBJECTs to return).
FORMAT: The format of the OBJECT processed by an
ACTION.
SOURCE FORMAT: The FORMAT of the SOURCE.
ACCESS: How the OBJECT of an ACTION could be
accessed.

Motivation
Fallbeispiel
Fazit und Ausblick
Vorbemerkungen
Thematische Rollen
Thematische Raster
Zusammenfassung
iDocIt! verfügt initial über 45 thematische Rollen (14 von
Girardi und Ibrahim + 31 aus dem seekda-Corpus)
Thematische Rollen können generalisier- und spezialisierbar
sein (z.B. FORMAT und SOURCE FORMAT)
Thematischen Rollen hängen nicht nur vom Prädikat ab (z.B.
ORDERING vom Numerus des OBJECT)

Motivation
Fallbeispiel
Fazit und Ausblick
Vorbemerkungen
Thematische Rollen
Thematische Raster
Vorgehensweise
1. Klassiﬁziere das als ACTION annotierte Pr¨adikat jeder
Operation in VerbNet.
2. Ordne alle thematische Rollen der Operation den
entsprechenden VerbNet-Kategorien zu.
3. Erprobe die so ermittelten thematischen Raster in Projekten
und passe sie ggf. manuell an.

Motivation
Fallbeispiel
Fazit und Ausblick
Vorbemerkungen
Thematische Rollen
Thematische Raster
Detailliertes Beispiel
Searching Operations
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.

Motivation
Fallbeispiel
Fazit und Ausblick
Vorbemerkungen
Thematische Rollen
Thematische Raster
Weitere Beispiele
Checking Operations
Converting Operations
Creating Operations
Describing Operations
Duplicating Operations
Establishing Operations
Getting Operations
Mathematical Operations
Merging Operations
Putting Operations
Removing Operations
Sending Operations
Starting Operations
Substituting Operations
Throwing Operations
Traversing Operations
Initializing Operations
Loading Operations
Sorting Operations

Motivation
Fallbeispiel
Fazit und Ausblick
Vorbemerkungen
Thematische Rollen
Thematische Raster
Zusammenfassung
Identifikation von 17 thematischen Rastern für Web Services
Praktischer Einsatz erbrachte drei weitere Raster
Zur Erinnerung:
Ziel von iDocIt! ist die Vereinfachung von API-Dokumentation
Wie kann die Komplexität thematischer Raster und Rollen
beherrschbar gemacht werden?

Motivation
Fallbeispiel
Fazit und Ausblick
Vorbemerkungen
Thematische Rollen
Thematische Raster
Grundkonzept: Steuerung der Empfehlung thematischer
Rollen durch Regeln.
Auswertungskontext ist immer die Operation, sowie alle ihr
¨ubergeordneten und untergeordneten Signaturelemente.
Rollenbasierte Regeln:
Steuerungsregeln als Eigenschaft einer thematischen Rolle
Rasterbasierte Regeln:
Steuerungsregeln als rollenspeziﬁsche Eigenschaft eines
thematischen Rasters

Motivation
Fallbeispiel
Fazit und Ausblick
Vorbemerkungen
Thematische Rollen
Thematische Raster
Rollenbasierte Regeln
Gegeben: das zu dokumentierende Signaturelement
Frage: Soll die jeweilige thematische Rolle zur
Dokumentation angeboten werden?
Aktuelle Implementierung iDocIt!:
Für jede Rolle ist definiert, auf welchen Ebenen sie zur
Dokumentation empfohlen wird.
Ebenen sind: Interface (relevant für AGENT), Operation
(relevant für ACTION) oder beides (Default)

Motivation
Fallbeispiel
Fazit und Ausblick
Vorbemerkungen
Thematische Rollen
Thematische Raster
Rasterbasierte Regeln
Gegeben: das zu dokumentierende Signaturelement und das
thematische Raster (Referenzraster)
Frage: Soll die jeweilige thematische Rolle zur
Dokumentation angeboten werden?
Aktuelle Implementierung iDocIt!:
Für jede Rolle eines Rasters existiert eine prädikatenlogische
Formel, die die Empfehlung der Rolle steuert.
Mögliche Prädikate in dieser Formel sind:
isSingular(”ROLLE”)
isPlural(”ROLLE”)
exists(”ROLLE”)
hasAttributes(”ROLLE”)

Motivation
Fallbeispiel
Fazit und Ausblick
Vorbemerkungen
Thematische Rollen
Thematische Raster
Beispiel zu rasterbasierten Regeln
Searching Operations
Rolle Status Zeige Rolle wenn ...
ACTION man immer()
AGENT man immer()
ALGORITHM opt immer()
COMPARISON opt !exists(”PRIMARY KEY”)
LIMIT opt isPlural(”OBJECT”)
OBJECT man immer()
ORDERING opt isPlural(”OBJECT”)
PRIMARY KEY opt !exists(”COMPARISON”)
SOURCE man immer()

Motivation
Fallbeispiel
Fazit und Ausblick
Vorbemerkungen
Thematische Rollen
Thematische Raster
Weiteres Beispiel zu rasterbasierten Regeln
Creating Operations
Rolle Status Zeige Rolle wenn ...
ACTION man immer()
AGENT man immer()
ATTRIBUTE opt hasAttributes(”OBJECT”)
DESTINATION man immer()
NAME opt !exists(”PRIMARY KEY”)
OWNER opt immer()
OBJECT man immer()
PRIMARY KEY opt !exists(”NAME”)

Motivation
Fallbeispiel
Fazit und Ausblick
Vorbemerkungen
Thematische Rollen
Thematische Raster
Live-Demo von rollen- und rasterbasierten Regeln
Live-Demo

Motivation
Fallbeispiel
Fazit und Ausblick
Analyse der Ebay Trading API
Ebay bietet Web Service zur Integration von Ebay-Diensten in
Anwendungen
Analysiert wird die Operation getFeedback(...)
Ziel: Identiﬁkation von Stille und Rauschen
Nutzung von iDocIt! als Analyse-Werkzeug

Motivation
Fallbeispiel
Fazit und Ausblick
Ergebnisse I
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]

Motivation
Fallbeispiel
Fazit und Ausblick
Ergebnisse I
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.

Motivation
Fallbeispiel
Fazit und Ausblick
Fazit
Fazit:
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
AKRA sammelt Erfahrungen mit diesem Verfahren in
mehreren Projekten
Offen bleibt: wie viel Dokumentation schafft wirklichen
Mehrwert?

Motivation
Fallbeispiel
Fazit und Ausblick
Fazit
Ausblick:
Empirischer Nachweis der Qualitätssteigerung durch iDocIt!
Zukünftiger Forschungsschwerpunkt: Beschreibung von
Aktivitäten in Prozessmodellen mit Hilfe thematischer Raster
Automatische Belegung thematischer Raster mit
dokumentierten, natürlichsprachlichen Inhalten

Motivation
Fallbeispiel
Fazit und Ausblick
Diskussion
Vielen Dank f¨ur Ihre Aufmerksamkeit.
Haben Sie Anmerkungen, Fragen oder Kritik?

Motivation
Fallbeispiel
Fazit und Ausblick
Quellen
Quellen:
Cartoon I: Widder, Oliver: ”Software Documentation?”;
veröffentlicht auf http://itmanagement.earthweb.com
Cartoon II: Widder, Oliver: ”Behind the Code?”;
veröffentlicht auf http://itmanagement.earthweb.com

iDocIt - Ein Assistent zur API-Dokumentation

Weitere ähnliche Inhalte

Mehr von Jan Christian Krause

iDocIt - Ein Assistent zur API-Dokumentation