iDocIt - Ein Assistent zur API-Dokumentation

MotivationAPI-Dokumentation mit iDocIt!

Thematische Rollen und Raster fur Web ServicesFallbeispiel

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



Fazit und Ausblick

Agenda

Motivation

API-Dokumentation mit iDocIt!Metaphern Stille und RauschenReminder: API-Dokumentation mit thematischen RasterniDocIt!

Thematische Rollen und Raster fur Web ServicesVorbemerkungenThematische RollenThematische RasterRollen und rasterbasierte Regeln

Fallbeispiel

Fazit und Ausblick




Fazit und Ausblick

Motivation - Cartoon I

Fur Quelle siehe letzte FolieJan Christian Krause(AKRA GmbH) iDocIt! - Ein Assistent zur API-Dokumentation



Fazit und Ausblick

Motivation - Cartoon II

Fur Quelle siehe letzte FolieJan Christian Krause(AKRA GmbH) iDocIt! - Ein Assistent zur API-Dokumentation



Fazit und Ausblick

Motivation - Fragen

I Ist der Code die Dokumentation?

I Worin besteht der Aufwand beim Dokumentieren?




Fazit und Ausblick

Metaphern Stille und RauschenReminder: API-Dokumentation mit thematischen RasterniDocIt!

Metaphern Stille und Rauschen

I Stille:Stille: Relevanter Aspekt der Operation, der in derDokumentation nicht erwahnt wird

I Rauschen:Irrelevante, redundante, nicht aktuelle oder unnotigausfuhrliche Dokumentation zu einem Aspekt der Operation

I Stille und Rauschen erzeugen Aufwand bei der Erstellung undbei der Konsultation von API-Dokumentation




Fazit und Ausblick


Reminder: API-Dokumentation mit thematischen Rastern




Fazit und Ausblick


iDocIt! - Ein Werkzeug zur API-Dokumentation

I Entstanden in der Bachelor-Arbeit von Dirk Meier-Eickhoff(AKRA GmbH)

I Eclipse Plugin (mind. Version 3.6)

I Dynamische Hinweise auf Stille

I Unterstutzt derzeit WSDL und Java (Erweiterbar um weitereProgrammier- und Markupsprachen (als Eclipse-Plugins))

I Open Source-Projekt bei Google Code(http://idocit.googlecode.com/)




Fazit und Ausblick


Live-Demo von iDocIt!

Live-Demo




Fazit und Ausblick

VorbemerkungenThematische RollenThematische RasterRollen und rasterbasierte Regeln

Vorbemerkungen

I iDocIt! benotigt thematische Rollen und Raster zurErkennung von Stille

I Thematische Rollen und Raster wurden empirisch auf Basisdes seekda-Corpus ermittelt.

Beschreibung Wert

Anzahl Dienstanbieter 8.947Anzahl WSDL-Beschreibungen 17.453Anzahl Port Types 24.474Anzahl Operationen 186.736




Fazit und Ausblick


Vorgehensweise

1. Erstelle eine Liste aller Operationen und entferne Dubletten.

2. Mische die Liste zufallig und spalte sie in Pakete mit je 50Operationen auf (Bezeichner, vollst. Input-, sowieOutput-Message und Faults).

3. Annotiere jedes Signaturelement jeder Operation mit einerthematischen Rolle (definiere ggf. eine passende Rolle). Initialwerden die 14 von Girardi und Ibrahim identifzierten Rollenvewendet.

4. Erfasse pro Paket die Anzahl der neu identifiziertenthematischen Rollen. Analysiere solange neue Pakete, bis derRollenzuwachs drei Mal 5% oder weniger betragt.




Fazit und Ausblick


Sattigungskurve

Corpus Große [Anzahl Pakete]

Th

emat

isch

eR

olle

n

0 1 2 3 4 5 610

20

30

40

50




Fazit und Ausblick


Tabelle

Paket∑

Rollen Neue Rollen Zuwachs [%] Ign. Operationen

0 14 14 0 01 31 17 1,21 12 37 6 0,19 23 42 5 0,14 14 44 2 0,05 25 44 0 0,00 26 45 1 0,02 5




Fazit und Ausblick


Beispiele

I ALGORITHM: Set of instructions how to perform theACTION.

I FORMULA: Formula used to compute a value during theACTION.

I OPERAND: Argument of a FORMULA.I ORDERING: The ordering of the returned OBJECTs.I LIMIT: The entity used to limit the ACTIONs space (e.g.

number of OBJECTs to return).I FORMAT: The format of the OBJECT processed by an

ACTION.I SOURCE FORMAT: The FORMAT of the SOURCE.I ACCESS: How the OBJECT of an ACTION could be

accessed.




Fazit und Ausblick


Zusammenfassung

I iDocIt! verfugt initial uber 45 thematische Rollen (14 vonGirardi und Ibrahim + 31 aus dem seekda-Corpus)

I Thematische Rollen konnen generalisier- und spezialisierbarsein (z.B. FORMAT und SOURCE FORMAT)

I Thematischen Rollen hangen nicht nur vom Pradikat ab (z.B.ORDERING vom Numerus des OBJECT)




Fazit und Ausblick


Vorgehensweise

1. Klassifiziere das als ACTION annotierte Pradikat jederOperation in VerbNet.

2. Ordne alle thematische Rollen der Operation denentsprechenden VerbNet-Kategorien zu.

3. Erprobe die so ermittelten thematischen Raster in Projektenund passe sie ggf. manuell an.




Fazit und Ausblick


Detailliertes Beispiel

Searching OperationsA searching operation searches for one or many OBJECTs at aSOURCE. The searched OBJECTs are identified by one or manyCOMPARISONs or PRIMARY KEYs. The number of foundOBJECTs could be limited by specifying a LIMIT. In case of manyOBJECTs an ORDERING defines their arrangement. TheALGORITHM defines the way the OBJECTs are searched. Thiscategory bases on the VerbNet classes Search-35.2 andobtain-13.5.2.




Fazit und Ausblick


Weitere Beispiele

I Checking Operations

I Converting Operations

I Creating Operations

I Describing Operations

I Duplicating Operations

I Establishing Operations

I Getting Operations

I Mathematical Operations

I Merging Operations

I Putting Operations

I Removing Operations

I Sending Operations

I Starting Operations

I Substituting Operations

I Throwing Operations

I Traversing Operations

I Initializing Operations

I Loading Operations

I Sorting Operations




Fazit und Ausblick


Zusammenfassung

I Identifikation von 17 thematischen Rastern fur Web Services

I Praktischer Einsatz erbrachte drei weitere Raster

Zur Erinnerung:

I Ziel von iDocIt! ist die Vereinfachung von API-Dokumentation

I Wie kann die Komplexitat thematischer Raster und Rollenbeherrschbar gemacht werden?




Fazit und Ausblick


Rollen und rasterbasierte Regeln

I Grundkonzept: Steuerung der Empfehlung thematischerRollen durch Regeln.

I Auswertungskontext ist immer die Operation, sowie alle ihrubergeordneten und untergeordneten Signaturelemente.

I Rollenbasierte Regeln:Steuerungsregeln als Eigenschaft einer thematischen Rolle

I Rasterbasierte Regeln:Steuerungsregeln als rollenspezifische Eigenschaft einesthematischen Rasters




Fazit und Ausblick


Rollenbasierte Regeln

I Gegeben: das zu dokumentierende Signaturelement

I Frage: Soll die jeweilige thematische Rolle zurDokumentation angeboten werden?

I Aktuelle Implementierung iDocIt!:

I Fur jede Rolle ist definiert, auf welchen Ebenen sie zurDokumentation empfohlen wird.

I Ebenen sind: Interface (relevant fur AGENT), Operation(relevant fur ACTION) oder beides (Default)




Fazit und Ausblick


Rasterbasierte Regeln

I Gegeben: das zu dokumentierende Signaturelement und dasthematische Raster (Referenzraster)

I Frage: Soll die jeweilige thematische Rolle zurDokumentation angeboten werden?

I Aktuelle Implementierung iDocIt!:

I Fur jede Rolle eines Rasters existiert eine pradikatenlogischeFormel, die die Empfehlung der Rolle steuert.

I Mogliche Pradikate in dieser Formel sind:

I isSingular(”ROLLE”)I isPlural(”ROLLE”)

I exists(”ROLLE”)I hasAttributes(”ROLLE”)




Fazit und Ausblick


Beispiel zu rasterbasierten Regeln

Searching OperationsRolle 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()




Fazit und Ausblick


Weiteres Beispiel zu rasterbasierten Regeln

Creating OperationsRolle 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”)




Fazit und Ausblick


Live-Demo von rollen- und rasterbasierten Regeln

Live-Demo




Fazit und Ausblick

Analyse der Ebay Trading API

I Ebay bietet Web Service zur Integration von Ebay-Diensten inAnwendungen

I Analysiert wird die Operation getFeedback(...)

I Ziel: Identifikation von Stille und Rauschen

I Nutzung von iDocIt! als Analyse-Werkzeug




Fazit und Ausblick

Ergebnisse I

Stille:

I Sortierung der zuruckgelieferten Bewertungen ist nichtspezifiziert [them. Rolle ORDERING]

I Unterschiedliche Datenquellen (Sandbox- undProduktivumgebung) sind nur unzureichend dargestellt [them.Rolle SOURCE]

I Berechnungsvorschrift fur die Feedback-Punktzahl ist nichtdokumentiert (findet sich an anderer Stelle in der EbayOnline-Hilfe) [them. Rolle FORMULA]




Fazit und Ausblick

Ergebnisse I

Rauschen:

I Vermeidung von Redundanz durch Nutzung der RollePRIMARY KEY fur ID- Felder (z.B. FeedbackID)

I Durch Anwendung des Lokalitatsprinzips bzgl.Felddokumentation lasst sich viel Rauschen der Kategorie 2einsparen, z.B. bei Feld DetailLevel.




Fazit und Ausblick

Fazit

Fazit:

I Thematische Raster konnen helfen Stille und Rauschen zuvermeiden

I Voraussetzung sind prazise gewahlte Verben in denOperationsbezeichnern

I Kardinalitaten thematischer Rollen sind nicht ableitbar

I AKRA sammelt Erfahrungen mit diesem Verfahren inmehreren Projekten

I Offen bleibt: wie viel Dokumentation schafft wirklichenMehrwert?




Fazit und Ausblick

Fazit

Ausblick:

I Empirischer Nachweis der Qualitatssteigerung durch iDocIt!

I Zukunftiger Forschungsschwerpunkt: Beschreibung vonAktivitaten in Prozessmodellen mit Hilfe thematischer Raster

I Automatische Belegung thematischer Raster mitdokumentierten, naturlichsprachlichen Inhalten




Fazit und Ausblick

Diskussion

Vielen Dank fur Ihre Aufmerksamkeit.Haben Sie Anmerkungen, Fragen oder Kritik?




Fazit und Ausblick

Quellen

Quellen:

I Cartoon I: Widder, Oliver: ”Software Documentation?”;veroffentlicht auf http://itmanagement.earthweb.com

I Cartoon II: Widder, Oliver: ”Behind the Code?”;veroffentlicht auf http://itmanagement.earthweb.com
