Home

Bachelorarbeit von Dirk Meier-Eickhoff

1. Schnittstellenelement Thematische Rolle Schnittstelle eBayAPIInterface AGENT Operation GetFeedback ACTION 2 SOURCE 2 FORMULA Eingabeparameter string FeedbackID PRIMARY KEY temIDType string ItemID PRIMARY KEY string TransactionID PRIMARY KEY UserIDType string UserID PRIMARY KEY Ausgabe int FeedbackScore OBJECT Tabelle 2 3 Auszug aus der Schnittstellenbeschreibung der Operation Get Feedback aus der eBay Trading API mit beispielhafter Zuordnung von thematischen Rollen Durch die Zuordnung der thematischen Rollen k nnen also nicht sichtbare Elemente aufgezeigt werden und so potentielle Stille in der O Doku vermieden werden Dar ber hinaus k nnen lange Beschreibungen durch die Zuordnung von Rollen eingespart werden Die in Tabelle 2 3 beschriebenen Eingabeparameter sind jeweils eigenst ndige Prim rschl ssel f r verschiedene Arten von gesuchten Objekten Durch die Zuordnung der Rolle PRIMARY KEY dem Parameter und dem Operationsbezeichner ist der Eingabeparameter aussagekr ftig beschrieben Der jeweilige erste Satz der Dokumentation ist somit redundant geworden und kann gestrichen werden 24 Vel 0 V eBay Trading API o J GetFeedback 17 2 Dokumentation von Operationen mit thematischen Rastern Eingabe parameter Dokumentation FeedbackID An I
2. 13 Abbildung 2 2 Beispielhafte K rzung der Dokumentation f r die Operation GetFeedback aus der eBay Trading API durch Zuordnung themetischer Rol na ee Besen 18 Abbildung 2 3 Rauschen in der O Doku am Beispiel des Eingabeparameters FeedbackID der Operation GetFeedback aus der eBay Trading API A NN Ns 19 Abbildung 2 4 Beziehungen thematischer Rollen zu Verbklassen 20 Abbildung 3 1 Aufbau eines Dokumentationsblocks eenenneeneen 24 Abbildung 4 1 Kategorien von Dokumentationssystemen ueeneenenesnenn 29 Abbildung 5 1 Aufteilung in fixe und variable Komponenten von iDoclt im Kontext Von Eclipsen nisen daa 37 Abbildung 5 2 Beispielhafter Aufbau eines lt portType gt Elements der WSDL 1 1 Spezifikation a O aa aik 42 Abbildung 5 3 Die Klasse Parameter mit den zusammengefassten Attributen 43 Abbildung 5 4 Klassendiagramm der allgemeinen Grammatik einer Schnittstellenstrukf r nu een 46 Abbildung 5 5 Auszug der abstrakten Klasse SignatureElement 47 Abbildung 5 6 Komponentendiagramm von iDoclt eeenenne 33 Abbildung 5 7 Einordnung der iDoclt Komponenten in die Drei Schichten Architekt ra sauna Sunshine 54 Abbildung 5 8 Klassendiagramm der Klasse ThematicGridService 54 Abbildung 5 9 Klassendiagramm der Klasse PersistenceService nenene 54 Abbildung 5 10 Klassendiagramm des Interf
3. 94 Abbildung 6 7 Abbildung 6 8 Abbildung 7 1 Abbildung 7 2 Abbildung 7 3 Abbildung 7 4 Abbildung 7 5 Abbildung D 1 Abbildung D 2 Abbildung D 3 Abbildung D 4 Abbildung D 5 Abbildung D 6 UI Klassen mit Methodennamen keine vollstandige Methodensienatun AAA E Gass 98 Auszug der Klasse DocumentltemListCompositeSelection 99 Auszug der Klasse GetFeedbackCall eeen 104 Screenshot der Klassenstruktur von GetFeedbackCall in iDoclt 105 In iDoclIt dokumentierte Methode GetFeedback der Klasse GrelFerdback all name 107 HTML Ansicht der iDoclt Dokumentation f r die Methode o ee een oes re 109 Realisierte Anforderungen im UL eier 112 iDoclIt Preference Par 133 iDoclt Preference Page f r Adressaten 133 iDoclt Preference Page f r thematische Raster 134 iDoclt Preference Page f r thematische Rollen 135 iDoclt Editor mit nicht unterst tzter Datei ge ffnet 136 iDoclt Editor mit der ge ffneten Klasse GetFeedbackCall aus dem EBay SDR for Java aio 137 1 Einf hrung 1 Einf hrung 1 1 Motivation Die Erstellung und Pflege von Software Dokumentation ist ein wichtiger und in der Praxis meistens aufwendiger Prozess Dies gilt insbesondere f r die Dokumentation von Schnittstellen Eine fehlende Dokumentation erschwert die Einarbeitung und Nutzung erheblich Ohne Dokumentation bleibt
4. get current selection object this documentItemCompositeDeleteButtonList indexOf e widget DocumentItemListCompositeSelection listSelection getSelection delete documentation out of the selection object listSelection getDocumentations remove row fireChangeEvent Tabelle 6 12 Auszug der Methode aus der Klasse Document ItemListComposite zum Entfernen einer Documentation 102 7 Systembewertung 7 Systembewertung Nachdem der Prototyp des Werkzeugs iDoclt entwickelt ist soll dieses nun bewertet werden Zuerst muss es sich in einem fiktiven Fallbeispiel bew hren Ein Teil der Klasse GetFeedbackCall aus dem eBay SDK for Java soll einmal mit den Bordmitteln von Eclipse mit Javadoc dokumentiert werden und einmal mit iDoclt Fur dieses Fallbeispiel wird Eclipse mit Javadoc verwendet und keins der in Kapitel 4 evaluierten Werkzeuge weil keins der Werkzeuge das Java Dokumentieren kann mehr als die sichtbaren Schnittstellenelemente einem Autor zur Dokumentation vorgibt Eclipse hat demnach die selbe Funktionalit t aber den Vorteil dass nicht noch ein Werkzeug detailliert beschrieben werden braucht Nach dem Fallbeispiel wird berpr ft ob iDoclt alle in Kapitel 3 hergeleiteten Anforderungen an ein Dokumentationssystem erf llt Abschlie end wird ein Fazit gezogen 7 1 Fallbeispiel In dem Fallbeispiel soll die Klasse GetFeedbackCall aus dem eBay SDK for Java sie
5. Tabelle 2 2 Beispiel eines thematischen Rasters f r das Verb to get im Kontext der Operation GetFeedback aus der eBay Trading API Aus dem thematischen Raster kann man ablesen dass get mehrere Argumente ben tigt Zum einen die Aktion ACTION selbst bei der ein OBJECT abgerufen werden soll Zudem ein Vergleichskriterium CRITERION bzw ein eindeutiger Schl ssel PRIMARY KEY das zum Finden des richtigen OBJECTs verwendet werden soll Au erdem werden eine Quelle SOURCE von wo die OBJECTs stammen und ggf wenn das OBJECT berechnet wird eine Formel FORMULA ben tigt Die Rolle AGENT ist nur implizit gegeben die z B der Benutzer das aufrufende Programm oder in der objektorientierten Welt das zugeh rige Objekt einnehmen kann Die Rollen AGENT ACTION und OBJECT sind in diesem Beispiel obligatorisch und die Rollen CRITERION SOURCE und FORMULA optional 20 Vgl Gruber J S Lexical Relations 1965 21 Vel Fillmore C J Case for Case 1968 S 1 90 15 2 Dokumentation von Operationen mit thematischen Rastern Wenn man die thematischen Rollen den Elementen der Operationssignatur zuordnet bemerkt man dass die Rollen e SOURCE und e FORMULA keinem Signaturelement zugeordnet werden k nnen siehe Tabelle 2 3 Man hat dadurch eine implizit verwendete Ressource und eine wichtig zu dokumentierende Eigenschaft der Operation erkannt und das ohne die Implementierungsdetails zu kennen Hierbei handelt es sich um nicht
6. 30 4 1 Kategorien von Dokumentationssystemen Kategorie 4 Format Die Kategorie 4 enthalt Formate die u a zur Schnittstellendokumentation verwendet werden k nnen Bei der Nutzung dieser Formate wird die Dokumentation auBerhalb des Quelltextes gespeichert Es findet keine Aufbereitung des vorhandenen Quelltextes statt DITA Darwin Information Typing Architecture und DocBook sind z B solche auf XML basierenden Formate in denen technische Dokumentationen verfasst werden k nnen Diese Formate k nnen durch zus tzliche Programme in andere Formate z B HTML oder PDF exportiert werden Zum Erstellen von Dokumentationen in diesem Format reicht ein einfacher Text bzw XML Editor 4 2 Unterst tzung der Dokumentation mit thematischen Rollen Da die Dokumentationssysteme der Kategorie 1 keine zus tzlichen Dokumentation ber cksichtigen und der Kategorie 2 nur Freitext erlauben gen gen sie den Anforderungen von Grund auf nicht Nur ein durch Schl sselw rter strukturiertes Format wie es in der Kategorie 3 und 4 verwendet wird gen gt den Anforderungen u a thematische Rollen und adressatenspezifische Beschreibungen zu unterst tzen Wie in den Tabellen 4 1 und 4 2 zu erkennen ist sind bei den meisten Formaten fast alle der von Clements et al empfohlenen Beschreibungen und auch weitere Metadaten mit einem Schl sselwort vorgesehen wie z B der Autor einer Schnittstelle oder ob die Schnittstelle veraltet ist Die meisten sin
7. 49 Vgl o V Java Platform Standard Edition 6 o J Package javax xml parsers 50 Vgl o V WSDLAJ o J 51 Vel 0 V Membrane SOA Model Java API for WSDL o J vil 6 2 Parser fiir WSDL 6 2 2 Struktur der Dokumentationen in WSDL Dokumentationen von iDoclt sollen in die optionalen lt documentation gt Elemente des lt definitions gt Elements und der einzelnen Elemente vom lt portType gt eingef gt werden k nnen In einem lt documentation gt Element darf Freitext aber auch eine Elementstruktur enthalten sein In einem Dokumentations block m ssen dabei eine thematische Rolle ein Sichtbarkeitsbereich ein Pfad zu dem dokumentierten Element und eine Menge von Adressaten mit jeweils einem Text untergebracht werden Wie eingangs erw hnt basiert die WSDL auf XML Deswegen soll keine neue Auszeichnungssprache f r die iDoclt Dokumentationen entwickelt werden sondern die M glichkeiten von XML genutzt werden Die Dokumentationen integrieren sich so nahtlos in die Struktur der WSDL Ein Dokumentationsblock wird in einem lt docpart gt Element realisiert Das lt docpart gt Element erh lt die Attribute role f r die thematische Rolle scope f r den Sichtbarkeitsbereich und signatureElement f r den Pfad zum dokumentierten Element Die Werte der Attribute role und signatureElement sind die des primitiven Datentyps string aus der XML Schema Definition Das Attribut scope darf nur die Werte EXPLICI
8. Die Liste und die Funktionen sollen in der Komponente DocumentationItemListComposite 2 realisiert werden In dieser Komponente soll sich an zentraler Stelle eine Schaltfl che befinden mit der Dokumentationsbl cke der Liste hinzugef gt werden k nnen Eine Zeile der Liste 63 5 4 User Interface UI besteht aus einem Dokumentationsblock und einer Schaltflache zum Entfernen der Dokumentation Ein Dokumentationsblock soll in einem DocumentationItemComposite 3 zusammengefasst werden Diese Komponente soll dynamische Auswahlm glichkeiten ftir eine thematische Rolle und einem Sichtbarkeitsbereich enthalten Weiterhin soll sie f r eine variable Menge an Adressaten jeweils ein Freitextfeld enthalten Sobald eine Anderung der Dokumentation erfolgt ist soll die neue Dokumentation ber die Speichern Schaltflache von Eclipse gespeichert werden k nnen Beim Selektieren einer Operation eines Parameters einer Operation oder eines Attributs eines Parameters im SelectSignatureElementComposite soll fiir das Verb der Operation die hinterlegten thematischen Raster angezeigt werden F r ein Verb k nnen mehrere thematische Raster mit unterschiedlichen thematischen Rollen definiert worden sein Daraus ergibt sich die Struktur einer Liste von Rastern mit jeweils einer Liste von Rollen Diese Struktur soll in der Komponente DisplayRecommendedRolesComposite 4 als Baumstruktur angezeigt werden F r eine bessere bersi
9. Unter Einbeziehung ihrer Kontexte also die Umgebung der Elemente bis zum Wurzelelement sind sie wieder eindeutig identifizierbar Select Signature Element E CustomerService java Artifact S O customerService Interface f Parameters I gt customer Type Customer G address Type Address gt firstName Type String id Type int name Type String o ReturnType lt gt Customer Type Customer lt 2 address Type Address firstName Type String lt P id Type int lt gt name Type String Abbildung 6 1 Beispiel der Wiederverwendung des Datentyps Customer In Abbildung 6 1 ist dieses beispielhaft an dem Datentyp Customer und seinen Attributen gezeigt Der Datentyp wird einmal als Eingabeparameter und einmal als Ergebnistyp verwendet Die einzelnen Attribute des Typs bilden jeweils ein SignatureElement Z B ist das Attribut name Type String im Kontext des Eingabeparameters und einmal im Kontext des Ergebnistyps vorhanden Es hat beide Male die gleichen Attribute und ist somit isoliert betrachtet identisch Wenn der gesamte Kontext dieses Elements betrachtet wird also der Pfad bis hoch zum Wurzelelement CustomerService java Artifact dann ist es wieder eindeutig Es w rden die Pfade CustomerService java CustomerService find customer name E CustomerService java CustomerService find Customer name 71 6 1 Plattf
10. die in Abbildung 5 4 zu sehen ist Da alle Elemente aus der allgemeinen Grammatik viele gleiche Attribute haben sind diese Gemeinsamkeiten in der Klasse SignatureElement zusammengefasst siehe Abbildung 5 5 45 5 1 Grammatiken lt lt Jawa Enumeration gt Scope de akra idocit structure lt lt Java Class gt gt G InterfaceArtifact de akra idocit structure lt lt Java Class gt gt ThematicRole de akra idocit structure 0 1 interfaces 0 scope j A NG thematicRole 0 1 lt lt Jawa Class gt gt Documentation de akra idocit structure lt lt Jawa Class gt gt Interface de akra idocit structure documentations lt lt Java Class gt gt SignatureElement lt de akra idocit structure 0 F N a operations 0 innerinterfaces lt lt Jawa Class gt gt Addressee de akra idocit structure lt lt Jawa Class gt gt Operation de akra idocit structure outputParameters D 1 lt lt Java Class gt Parameter k de akra idocit structure complexType 0 parameters sadaya Class gt Parameters lt de akra idocit structure 0 exceptions 0 1 inputParameters Abbildung 5 4 Klassendiagramm der allgemeinen Grammatik einer Schnittstellenstruktur Ein SignatureElement besitzt eine Menge von Dokumentationsbl cken documentations wobei ei
11. html FORMULA Associated OBJECT Associated SOURCE AGENT Mi Abbildung 7 3 In iDoclt dokumentierte Methode Get Feedback der Klasse GetFeedbackCall Als erstes k nnen die thematischen Rollen den sichtbaren Elementen der Methode zugeordnet werden siehe Abbildung 7 3 Die Rolle ACTION erh lt die Methode zusammen mit einer allgemeinen Beschreibung ihrer Aktion Danach wird die Rolle OBJECT dem Ergebnistypen zugeordnet und das Ergebnis beschrieben Nun sind die nicht an der Methode sichtbaren Elemente dran Dazu z hlt die zugrunde liegende Formel FORMULA die Quelle der Daten SOURCE wer die ausf hrende Instanz AGENT der Methode ist und das Kriterium PRIMARY KEY das entscheidet fiir wen oder was das Feedback abgerufen werden soll Die Rolle FORMULA wird der Methode zugeordnet und dort wird die Berechnungsvorschrift auch beschrieben Die Rolle PRIMARY KEY kann keinem 107 7 1 Fallbeispiel Element der Methode zugeordnet werden da diese Einstellung woanders geschieht Auch die Rolle AGENT kann nicht der Methode zugeordnet werden da sie sich nicht selbst ausf hrt In der objektorientierten Welt f hrt das Objekt der Methode diese aus Die Rolle AGENT wird demnach der Klasse Get FeedbackCall zugeordnet Die Rolle SOURCE kann der Methode zugeordnet werden aber da keine z B Datenbankverbindung oder Datei als Eingabeparameter in die Methode hineingeht wird die Datenquelle auf Klassenebene v
12. siehe Tabelle 7 1 werden diese drei in der Oberfl che Abbildung 7 2 im Bereich unten links als Vorschlag von zu dokumentierenden Elementen angezeigt Hier zeigt sich die erw hnte Schwierigkeit Da get ein unpr zises Verb ist kann es in vielen Kontexten verwendet werden Der Autor muss dann entscheiden um welchen Kontext es sich handelt und dementsprechend ein Raster w hlen an das er sich beim Dokumentieren h lt In diesem speziellen Fall ist die Entscheidung f r ein Raster schwierig denn die Methode kann zu den Kontexten aller drei thematischen Raster zugeordnet werden Je nach dem Standpunkt kann man sagen dass nur ein Wert abgerufen wird also w rde das Getter Raster passen Man k nnte auch sagen dass das Feedback Resultat vieler Einzelbestandteile ist Es wird also mit einer definierten Formel berechnet Dann w rde das Calculating Operations Raster passen Oder man nimmt an dass das Feedback f r einen Benutzer oder Artikel Item usw gesucht wird z B aus einer Datenbank Daf r w rde das Searching Operations Raster passen In so einem speziellen Fall w re ein Mix von den Rastern m glich denn die thematischen Raster bieten ein Standard Portfolio an thematischen Rollen an die in der Regel f r ein Verb dokumentiert werden sollten Die Methode getFeedback ruft nicht nur einen einfachen Wert ab sondern einen aus verschiedenen Bestandteilen und Bedingungen berechneten Wert Au erdem macht
13. 1 1 da die Version 2 0 bei der AKRA GmbH noch nicht eingesetzt wird Ausgehend davon dass eine Schnittstelle aus irgendeiner Quelle ausgelesen werden kann wird diese i d R eine Datei sein auf die sich auch iDoclt beschr nkt Die Quelle soll in der allgemeinen Schnittstellenstruktur aber trotzdem allgemein InterfaceArtifact hei en In diesem Artefakt k nnen mehrere Schnittstellendefinitionen enthalten sein in Java z B mehrere Schnittstellen interfaces Selbiges gilt in der WSDL Hier kann ein Artefakt mehrere lt portType gt Elemente enthalten die zur Beschreibung einer Schnittstelle verwendet werden Abstrahiert man die erw hnten Teile zu einer allgemeinen Struktur besteht ein Artefakt aus einer Menge von allgemeinen Schnittstellenstrukturen die Interface hei en sollen Eine Schnittstelle in Java enth lt eine Menge von Operationen Methoden und kann aber auch wieder eine Menge innerer Schnittstellen enthalten Bei der WSDL enth lt das lt portType gt Element nur Operationen lt operation gt Elemente siehe Tabelle 5 2 Demnach muss eine allgemeine Schnittstellenstruktur aus einer Menge von Operationen die Operation hei en sollen und einer Menge von inneren Schnittstellen Interface bestehen 37 Vel Gosling James et al Java Language Specification 2005 38 Siehe Anhang C Java Interface Deklaration 39 Vgl Christensen Erik et al WSDL 1 1 2001 40 Siehe Anhang B WSDL 1 1 Spe
14. 23 3 3 A a 25 3 4 Vorgaben det AKRA GmbH iii dl ti ica 28 4 Existierende Dokumentationssysteme ssccccsccccssccccsscssssecssssscsssssesccssessoees 29 4 1 Kategorien von DokumentationssysteMen ccccceesseesseeeseceeeeeeeeeeeeeeaeeeees 29 4 2 Unterst tzung der Dokumentation mit thematischen Rollen 31 IA AAA AS 36 NAAI AANE O 37 O nl 38 5 1 1 Grundlagen formaler GrammatikeN oooooccnccinocinococonoconannnnnoncconnnnccnnnnnnnos 38 5 1 2 Generische Grammatik f r Schnittstellen 40 5 2 Modularisierung und Erweiterbarkelt ooonoonnnccinocinococonnconnnonnncncononononnocccnonoss 48 32 1 Belipse Pluoms A rn 49 3 2 2 WD OC 2 er era 50 5 3 Parser f r Schnittstellen u e aaa 56 3 4 User Interface Ds nem an 62 5 5 Kommunikation der Plattform ServiceS ooonoccnoconocnnoocnconncnnnnncnnonancnnnanononannnno 66 6 Implementierung sun ER 70 6 1 Plattform Core iii 70 6 1 1 Abstrakte Schnittstellenstruktur cccsccssccsscssserssssscsencssessacsssaccnseseees 70 612 Parser Extension Pont anne a Ban 75 6 2 Parser f r WSDE seers Boat oho teeta Tae oer ete cde nn a aha Gunde 76 6 2 1 Existierende XML WSDL Pas a Re use 71 6 2 2 Struktur der Dokumentationen in WSDL ennnnnennnenen 78 6 2 3 Implementierungsdetails des WSDL Parsers nenen 80 o A kt 87 6 3 1 Existierende Paver aussehen 88 6 3 2 Struktur der Dokumentation in JavVadoOC oooc
15. A 6 Links zu den untersuchten Dokumentationssystemen 125 B WSDL 1 1 Spezifikation B WSDL 1 1 Spezifikation Die in Tabelle B 1 und Tabelle B 2 verwendeten Datentypen qname nmtoken und uri geh ren zu den eingebauten Datentypen QName NMTOKEN und anyURI der XML Schema Definition Legende Optional 0 bis 1 Mal vorhanden Mehrfach vorhanden 0 bis beliebig oft lt wsdl definitions name nmtoken targetNamespace uri gt lt import namespace uri location uri gt lt wsdl documentation gt lt wsdl types gt lt wsdl documentation gt lt xsd schema gt lt extensibility element gt lt wsdl types gt lt wsdl portType name nmtoken gt lt wsdl documentation gt lt wsdl operation name nmtoken gt lt wsdl documentation gt lt wsdl input name nmtoken message qname gt lt wsdl documentation gt lt wsdl input gt lt wsdl output name nmtoken message qname gt lt wsdl documentation gt lt wsdl output gt lt wsdl fault name nmtoken message qname gt lt wsdl documentation gt lt wsdl fault gt lt wsdl operation gt lt wsdl portType gt Tabelle B 1 WSDL 1 1 Spezifikation 73 Vgl Biron Paul V Malhotra Ashok XML Schema Part 2 2001 74 Vel Christensen Erik et al WSDL 1 1 2001 126 B WSDL 1 1 Spezifika
16. Darwin Information Typing Architecture Document Object Model Erweiterte Backus Naur Form GNU is not Unix GNU Free Documentation License GNU General Public License siehe GNU GPL Graphical User Interface HyperText Markup Language Identifikation snummer Massachusetts Institute of Technology ohne Jahr ohne Ort ohne Verfasser Operationsdokumentation Portable Document Format Process Oriented Construction of User Interfaces 139 E Abkiirzungsverzeichnis Std SWT UI UML URL WSDL XML Standard Standard Widget Toolkit User Interface Unified Modeling Language Uniform Resource Locator Uniform Resource Identifier Webservice Description Language Extensible Markup Language 140 Literaturverzeichnis Literaturverzeichnis Literaturverzeichnis Clements Paul et al 2008 Documenting Software Architectures Views and Beyond 10 Crawfordsville IN US Addison Wesley Professional 2008 Fillmore C J 1968 The Case for Case in Universals in Linguistic Theory New York US Holt Rinehart and Winston 1968 S 1 90 Gosling James et al 2005 The Java Language Specification Third Edition Addison Wesley 2005 Internet http java sun com docs books jls third_ edition html j3TOC html Abruf 11 01 2011 Gruber J S 1965 Studies in Lexical Relations Massachusetts US Massachusetts Institute of Technology 1965 Krause Jan Christian Joneleit Kai
17. Generator N a Imagix 4D E a Universal Report RDoc E dE _ A CppDoc a Doc O Matic o DOC 2 Document X F o Doxygen ite o GenHelp o HeaderDoc o T Javadoc o o Natural Docs T o ROBODoc o TwinText E VSdocman o YARD o DITA o o o o o DocBook o o o o o Tabelle A 3 Fortsetzung Unterst tzte Dokumentationstypisierungen von den untersuchten Dokumentationssystemen 122 A Auswahl existierender Dokumentationssysteme Nicht sichtbare Elemente Name abbildbar ableitbar Help Generator Imagix 4D Universal Report RDoc 2 CppDoc o Doc O Matic o DOC Document X o Doxygen o a GenHelp o 7 HeaderDoc Javadoc o z Natural Docs o ROBODoc TwinText E z VSdocman o a YARD o DITA o DocBook o Tabelle A 4 Unterst tzung nicht sichtbarer Elemente von den untersuchten Dokumentationssystemen 123 A Auswahl existierender Dokumentationssysteme Unterstiitzte Programmier und Beschreibungssprachen Erweiterbar f r Anzahl Sprachen mit Name Java WSDL insgesamt Kommentaren CppDoc Nein Nein 1 Nein Doc O Matic Ja Nein 11 Ja DOC Ja Nein 3 Nein Document X Nein Ja 4 Nein Doxygen Ja Nein 11 Nein GenHelp Nein Nein 3 Nein He
18. J eBay SDK for Java Internet http developer ebay com developercenter java sdk Version 687 Abruf 18 02 2011 o V 0 J eBay SDK for Java Library Reference Documentation Internet http developer ebay com DevZone javasdk jaxb docs LibRef index html Version 687 Abruf 18 02 2011 o V 0 J eBay help How Feedback works Internet http pages ebay com help feedback howitworks html Abruf 10 01 2011 o V 0 J eBay Developer s Sandbox Internet http www sandbox ebay com Abruf 10 01 2011 o V 0 J Eclipse Helios Version 3 6 1 Internet http www eclipse org Abruf 01 02 2011 o V 0 J How to Write Doc Comments for the Javadoc Tool Internet http www oracle com technetwork java javase documentation index 137868 html Abruf 10 01 2011 o V 0 J OSGi Alliance fr her Open Services Gateway initiative Internet http www osgi org Abruf 01 02 2011 0 V 0 J Xerces2 Java Parser Version 2 11 0 Internet http xerces apache org xerces2 j Abruf 16 02 2011 0 V 0 J Java Platform Standard Edition 6 API Specification Version 6 Internet http download oracle com javase 6 docs api Abruf 16 02 2011 0 V 0 J Membrane SOA Model Java API for WSDL and XML Schema Version 1 0 2 Internet http www membrane soa org soa model Abruf 16 02 2011 0 V 0 J Web Services Description Language for Java Toolkit WSDLAJ Version 1 6 2 Internet http sourceforge net projects wsdl4j Abru
19. SDK for Java als Basis verwendet und leicht ver ndert damit die Aspekte besser dargestellt werden k nnen Es wurde eine Klasse User mit dem Attribut id vom Typ String erstellt und als Eingabeparameter der Methode GetFeedback verwendet Weiterhin ist nur eine der drei Ausnahmen der Methode exemplarisch aufgef hrt Wie in dem Beispiel zu sehen ist werden die Dokumentationsbl cke entsprechend den dokumentierten Elementen an den richtigen Stellen eingef gt Beispielsweise werden Dokumentationsbl cke f r eine generelle Beschreibung an den Anfang eines Javadoc Kommentars geschrieben ohne ein Tag und die Dokumentationsbl cke f r Eingabeparameter zu dem jeweiligen Tag des Parameters In dem Beispiel zu dem Tag param user 62 Vel 0 V eBay SDK for Java Library Reference Documentation 0 J GetFeedbackCall 90 6 3 Parser fiir Java o FeedbackDetailType com ebay sdk call GetFeedbackCall getFeedback User user throws ApiException SdkException Exception Role ACTION Developer Retrieves the accumulated feedback left for a specified user Role FORMULA Scope implicit Tester Look at http pages ebay com help feedback howitworks html Parameters user Element user com ebay sdk call User fcom ebay sdk call User id java lang String Role PRIMARY KEY Developer The unique user name Tester If id is not initialized SdkException is thrown Returns res com ebay soap eBLBaseComponents FeedbackDeta
20. Verben erstellt werden In der Klasse werden nur zwei verschiedene Verben verwendet get und set Das mag erst einmal f r das Erstellen der Raster positiv erscheinen birgt aber Schwierigkeiten f r das Dokumentieren auf die sp ter eingegangen wird Zuerst sollen die thematischen Raster definiert werden In Tabelle 7 1 sind die thematischen Raster aufgef hrt die f r das Fallbeispiel verwendet werden sollen Da das Verb get in verschiedenen Kontexten verwendbar ist wird es auch verschiedenen thematischen Rastern Verbklassen zugeordnet mit unterschiedlichen thematischen Rollen Das Verb set ist dagegen nur einem Raster zuordenbar Damit der Kontext jedes Rasters besser verst ndlich ist bekommen sie Namen z B Calculating Operations und z T sind weitere Verben aufgef hrt 104 7 1 Fallbeispiel Verbklasse Verben Thematische Rollen Thematisches Raster Setter set AGENT ACTION OBJECT SOURCE Getter get AGENT ACTION OBJECT SOURCE Calculating Operations compute AGENT ACTION OBJECT SOURCE calculate get FORMULA Searching Operations search find AGENT ACTION OBJECT SOURCE seek get CRITERION PRIMARY KEY Tabelle 7 1 Definierte thematische Raster f r das Fallbeispiel Select Signature Element Document Signature Element getFeedback Method Add Thematic Role documentation j GetFeedbackCall java Artifact S GetFeedbackcall Class O GetFeedbackCa
21. WSDL Dadurch werden diese beim Zur ckschreiben der WSDL gel scht F r diese Bachelorarbeit ist der Mangel noch tragbar aber das Verhalten w re f r den produktiven Einsatz in der Praxis nicht haltbar 80 6 2 Parser fiir WSDL 3 Mangel WSDL4J beriicksichtigt beim Einlesen der WSDL nur fest definierte Attribute eines Elements andere werden ignoriert In Tabelle 6 5 sind die fiir diese Bachelorarbeit wichtigen WSDL Elemente mit ihren unterstiitzten Attributen aufgef hrt Dadurch k nnen wichtige Informationen beim Einlesen verloren gehen die beim Schreiben nicht mehr ber cksichtigt werden k nnen In dem aktuellen Prototyp von iDoclt ist dieses Problem noch nicht behoben worden was aber in einer nachfolgenden Version unbedingt gemacht werden sollte Element Attribute definitions name targetNamespace xmlns portType name operation name parameterOrder input name message output name message fault name message message name part element type Tabelle 6 5 Auszug von WSDL Elementen mit den von WSDL4J unterst tzten Attributen In Kapitel 5 1 2 wurden die f r iDoclt wichtigen Teile der WSDL 1 1 Spezifikation bereits vorgestellt In Tabelle 6 6 ist die Spezifikation dieser Teile noch einmal zusammenh ngend aufgef hrt damit die Zuordnung zu den Klassen der allgemeinen Schnittstellenstruktur gezeigt werden kann Die Parser Erweiterung soll vom lt definiti
22. Wenn eine sehr umfassende API Dokumentation wie z B die von der eBay Trading API auf eine iDoclt Dokumentation umgestellt wird sollte sie potentiell k rzer ausfallen Das Lokalit tsprinzip f r Dokumentation wird von iDoclt auch umgesetzt Dokumentationen werden dort erfasst wo sie ben tigt werden Das wird z B bei den Beschreibungen der Attribute von Parametertypen deutlich Ein Datentyp kann in verschiedenen Kontexten eingesetzt werden und hat jeweils eine andere Bedeutung Jeder Kontext verlangt eine eigene Beschreibung die am Verwendungsort stehen sollte und nicht mit Fallunterscheidungen direkt beim Datentyp Die konzeptionelle Unterst tzung eines Autors beim Dokumentieren einer Schnittstelle ist also auf jeden Fall sp rbar Das Benutzungsmodell sollte aber noch verfeinert und auch erweitert werden 115 8 Abschlussbetrachtungen 8 Abschlussbetrachtungen Abschlie end zu dieser Bachelorarbeit wird noch einmal das Ergebnis zusammengefasst und ein Ausblick f r dieses Thema und das Werkzeug iDoclt gewagt Weiterhin werden noch m gliche Weiterentwicklungen f r iDoclt vorgestellt 8 1 Zusammenfassung und Ausblick In dieser Bachelorarbeit wurde evaluiert inwieweit existierende Dokumentations systeme und haupts chlich Dokumentationswerkzeuge den Ansatz unterst tzen Dokumentationen mit thematischen Rastern und Rollen zu erstellen Dazu wurden 19 Dokumentationssysteme im Internet recherchiert und deren Fun
23. ausformuliert wiedergibt siehe Abbildung 2 3 Da er keine neuen Informationen 18 2 Dokumentation von Operationen mit thematischen Rastern enthalt kann er einfach gestrichen werden Eine Dokumentation soll nicht den Quelltext wiedergeben sondern nicht offensichtliche Informationen beschreiben GetFeedback FeedbackID An ID that uniquely identifies a feedback record to be retrieved Abbildung 2 3 Rauschen in der O Doku am Beispiel des Eingabeparameters FeedbackID der Operation Get Feedback aus der eBay Trading API Wie weiter oben schon angedeutet zeigt Tabelle 2 2 ein thematisches Raster f r das Verb get in einer bestimmten Anwendungssituation Kontext In einem anderen Kontext w ren vielleicht andere thematische Rollen passender wobei einige Rollen AGENT ACTION und OBJECT immer bestehen bleiben w rden da sie die obligatorischen Argumente des Verbs sind Eigentlich m sste f r jedes Verb in jedem m glichen Kontext ein thematisches Raster definiert werden um alle m glichen F lle abbilden zu k nnen Praktisch ist dieses aber aber nur mit grofem Aufwand realisierbar Daher sollten Verben die h ufig in bestimmten Kontexten verwendet werden in Klassen aufgeteilt werden Das hat den Vorteil dass nicht f r viele einzelne Verben ein thematisches Raster definiert werden muss sondern f r wenige Klassen von Verben Eine Klasse enth lt z B Verben die im Kontext einer Suche verwendet werden
24. bekannt sind 12 Vel 0 V Javadoc 0 J A Style Guide 13 Vgl Martin Robert C Clean Code 2009 S 61 71 14 Vel Krause Jan Christian Thematic Grids 2010 13 2 Dokumentation von Operationen mit thematischen Rastern Ein Satz wird in der nat rlichen Sprache haupts chlich durch das verwendete Verb beschrieben Akteure oder Attribute einer Handlung sind dabei syntaktisch und semantisch abh ngig von dem Verb Die Akteure und Attribute werden auch Argumente des Verbs genannt die obligatorisch oder optional sein k nnen Schnittstellenelement Dokumentation Operation GetFeedback Use this call to retrieve the accumulated feedback left for a specified user Eingabeparameter string FeedbackID An ID that uniquely identifies a feedback record to be retrieved temIDType string ItemID The ID of the item that you want feedback data about string TransactionID Transaction ID whose feedback record you want to inspect UserIDType string UserID Specifies the user whose feedback data is to be returned Ausgabe int FeedbackScore Indicates the total feedback score for the user Tabelle 2 1 Auszug aus der Schnittstellenbeschreibung der Operation GetFeedback aus der eBay Trading API In den Programmiersprachen hat sich wegen der starken Aussage des Verbs etabliert dass ein Operationsbeze
25. der Benutzer Anderungen am InterfaceArtifact vorgenommen hat Ist dies der Fall so wird die Speichern Schaltflache von Eclipse aktiviert Alle direkt von SignatureElement erbenden Klassen berschreiben die ffentliche Methode copy In deren Implementierung wird als erstes immer die berschriebene Methode in SignatureElement auf super copy parent Der Parameter parent ist dabei das neue Elternobjekt f r die Kopie des SignatureElement s Damit dieser Ablauf nicht manipuliert werden kann muss die Methode in allen von SignatureElement erbenden Klassen als final nicht weiter berschreibbar deklariert werden Das Codebeispiel in Tabelle 6 1 zeigt dieses an der Klasse Parameters In der copy Methode des SignatureElement s wird dann zuerst die abstrakte Methode createSignatureElement aufgerufen siehe Tabelle 6 2 Diese Methode ist nicht in der Klasse Parameters sondern in der von Parameters erbenden Klasse implementiert z B in der Klasse WSDLMessage aus der WSDL Parser Erweiterung siehe Tabelle 6 3 Diese Klasse repr sentiert ein lt message gt Element in der WSDL In dieser Methode wird ein neues Objekt der Subklasse 73 6 1 Plattform Core WSDLMessage erzeugt und zur ckgegeben Danach werden in copyAttributesTo alle Attribute des SignatureElement s und in doCopyTo alle Attribute der von Parameters erbenden Klasse in das newSigElem kopiert Die abstrakte Methode doCopyTo muss auch wie
26. deriveThematicGridfidentifier String Map lt String Set lt ThematicRole gt gt Abbildung 5 8 Klassendiagramm der Klasse ThematicGridService de akra idocit services PersistenceService O _loadInterface iFile IFile InterfaceArtifact O writelnterfacelinterface rtifact Interface rtifact iFile IFile void Abbildung 5 9 Klassendiagramm der Klasse PersistenceService Die Methode deriveThematicGrid String identifier in der Klasse ThematicGridService extrahiert aus einem Operations Bezeichner das Verb und gibt die f r das Verb definierten thematischen Raster mit ihrer Menge an zugewiesenen thematischen Rollen zur ck Map lt String Set lt ThematicRole gt gt Die Klasse PersistenceService bietet die Methode loadInterface an Diese Methode erstellt mit Hilfe der Parser Erweiterungen aus 54 5 2 Modularisierung und Erweiterbarkeit unterstiitzten Eclipse Dateiressourcen Datentyp IFile InterfaceArtifacts Mit der Methode writeInterface wird ein manipuliertes InterfaceArtifact mit Hilfe einer Parser Erweiterung wieder in eine Dateiressource geschrieben Auch die abstrakte allgemeine Schnittstellenstruktur Abstract Interface Artifact Structure sowie das Interface Parser siehe Abbildung 5 10 sind in der Core Komponente enthalten Dieses Interface ist in dem bereitgestellten Extension Point Vertragsbestandteil Es enthalt die Methoden parse zum Parsen einer Da
27. einem Konsumenten einer Schnittstelle nur das Lesen des Quelltextes der Implementierung oder Ausprobieren verschiedener Eingaben um deren Nutzungsweise zu erfahren Erstere M glichkeit entf llt h ufig weil der Quelltext der Implementierung nicht immer verf gbar ist wie z B bei Webservices oder Schnittstellen propriet rer Systeme Daher sollte die pr zise knappe verst ndliche und vollst ndige Dokumentation der Schnittstelle und ihrer Operationen angestrebt werden Die Dokumentation von Schnittstellen wird in Projekten meist stiefm tterlich behandelt Oft sind sie unvollst ndig teils auch schwer verst ndlich und nicht einheitlich gestaltet In vielen F llen liegt dies am konzeptionellen Aufwand sowie fehlenden stilistischen oder inhaltlichen Vorgaben Um festzustellen ob eine Operationsdokumentation O Doku vollst ndig ist bekommt der Autor nur rudiment re Unterst tzung von Werkzeugen In der Regel wird ein Raster der ffentlich sichtbaren Elemente der Operationssignatur vorgegeben z B die formalen Parameter oder R ckgabewerte Der u erliche Stil wird zwar durch durchg ngig genutzte Formate wie Javadoc vereinheitlicht aber die inhaltliche Qualit t der Dokumentation variiert je nach Autor 1 Vgl Clements Paul et al Documenting Software Architectures 2008 S 228 239 2 Vel Schraitle Thomas Value of Good Documentation 2009 3 Vgl Reilly Annette D et al IEEE Std 1063 2001 2001 S Sff
28. f r die Fehler ben tigt wird in Java 42 5 1 Grammatiken eine Menge von Parameters mit jeweils einer Ausnahme gebildet Eine einzelne Java Ausnahme wird also wie eine WSDL lt message gt behandelt o dataTypeName String o qualifiedDataTypeName String o complexType List lt Parameter gt Abbildung 5 3 Die Klasse Parameter mit den zusammengefassten Attributen Wie in den Anforderungen beschrieben sollen auch Attribute der Eingaben Ausgaben und Fehler bzw Ausnahmen dokumentiert werden k nnen Da alle prinzipiell die gleichen Eigenschaften Attribute haben sollen sie unter dem Begriff Parameter zusammengefasst werden siehe Abbildung 5 3 Um die Attribute eines Parameters abzubilden erh lt die Klasse eine weitere Struktur In Java kann ein Parameter ein strukturierter z B List Set usw oder ein unstrukturierter Datentyp z B int long double char usw sein In WSDL beschreibt ein komplexer oder einfacher Typ die Struktur eines Elements Das Element selbst braucht demnach nicht separat behandelt werden da die Typen ausschlaggebend sind Bei einem einfachen Typen SimpleType braucht ein Parameter keine weitere Struktur da es keine weiteren Attribute gibt Bei einem komplexen Typ bzw strukturierten Datentyp k nnen beliebig viele Attribute vorhanden sein Da Attribute und Parameter die gleichen Eigenschaften haben werden sie auch als Parameter abgebildet Ein Parameter erh lt somit fiir die innere
29. gt und mit removeAllListener wieder entfernt In der Methode doCleanUp werden alle Ressourcen freigegeben die nicht automatisch von z B dem Java Garbage Collector freigegeben werden 70 Vel Krause Jan Christian Joneleit Kai Benjamin Prozessorientierte Konstruktion von Benutzeroberfl chen 2009 97 6 4 User Interface UI C DisplayRecommendedRolesComposite O DisplayRecommendedRolesComposite AbsComposite gt initGUIC gt doSetSelection gt initListener gt add llListener gt removedAllListener gt doCleanUpt C org pocui swt composites AbsComposite getResourceConfiguration getActionConfiguration IEG inklistener cleanUp void addSelectionListener removeSelectionListener fireChangeEvent getSelection setSelection dosetselectionii gt initGUIC addtltitener initListener removeAll stener doSetSelection gt addAllListener gt removedllistener doCleanUpt EditArtifactDocumentationComposite 06000350000 SelectSignatureElementComposite O DocumentltemListComposite initGUIC initGUIC initListener initListener doSetSelection doSetSelection addallListener addAllListener removedllListener removedlllistener doCleanUpt doCleanUp C DocumentItemComposite DocumentItemComposite gt initGUIC gt
30. hren Von der Parser Erweiterung werden nur bestimmte Teile der Java Spezifikation Elementen aus der allgemeinen Schnittstellenstruktur zugeordnet Die restlichen Teile m ssen aber trotzdem eingelesen und behandelt werden damit die Datei vollst ndig geschrieben werden kann Um den Entwicklungs und Implementierungsaufwand f r einen vollst ndigen Parser f r Java mit zur ckschreiben der Daten zu vermeiden wird auf einen existierenden Parser zur ckgegriffen Zun chst werden einige existierende Parser evaluiert ob deren Funktionalit t f r den Zweck Java mit Javadoc Kommentaren zu parsen und zu speichern ausreicht Daran folgend wird die Struktur der Dokumentationen von iDoclt entwickelt wie sie sich in Javadoc integrieren soll Zum Schluss werden einige Details zur Implementierung beschrieben 87 6 3 Parser fiir Java 6 3 1 Existierende Java Parser Es existieren einige Parser fiir die Programmiersprache Java die eine Java Objektstruktur aus einer Java Quelldatei erstellen k nnen Fiir die Implementierung der Java Parser Erweiterung wurden u a JaxMeJS JaxMe JavaSource javapaser und die Eclipse JDT Java development tools n her evaluiert Die API des JaxMeJS Frameworks bietet alle n tigen Methoden um eine Java Quelldatei zu parsen zu manipulieren und wieder zu speichern Javadoc Kommentare k nnen Elementen hinzugef gt werden und in diesen k nnen sogar einzelne Javadoc Tags eingef gt werden Aber lei
31. http pages ebay com help feedback howitworks html Parameters user Element user com ebay sdk call User com ebay sdk call User id java lang String Role PRIMARY KEY Developer The unique user name Tester If id is not initialized SdkException is thrown Returns icom ebay soap eBLBaseComponents FeedbackDetailType icom ebay soap eBLBaseComponents FeedbackDetailType Role OBJECT Developer The FeedbackDetailType object Throws ApiException SdkException Exception Abbildung 7 4 HTML Ansicht der iDoclt Dokumentation f r die Methode Get Feedback Element 7 1 2 Dokumentation mit Eclipse und Javadoc Fir die Dokumentation mit Eclipse sind keine Vorbereitungen n tig Die Dokumentation wird auch direkt in den Quelltext geschrieben Das Javadoc Raster wird erstellt indem ber der Methode getFeedback mit ein Kommentarblock angefangen wird und dann die Enter Taste gedr ckt wird Dann wird das Raster mit den sichtbaren Elementen der Methodensignatur erstellt siehe Tabelle 7 2 109 7 1 Fallbeispiel pk return public FeedbackDetailType getFeedback Tabelle 7 2 Javadoc Raster f r getFeedback Das Raster schl gt zur Dokumentation nur den Ergebnistypen return und eine allgemeine Freitextbeschreibung vor Leerzeile am Anfang des Kommentars Nach der Beschreibung beider Elemente ist die Methode mit den notwendigen Tags nach der Javadoc Ko
32. in den voll qualifizierten Namen und den Datentyp zu teilen und eins um den einfachen Namen Bezeichner vom qualifizierenden Teil Namensraum zu trennen Diese Trennzeichen m ssen so gew hlt werden dass sie in der jeweils zugrunde liegenden Programmier oder Beschreibungssprache keine Konflikte verursachen Dazu k nnen z B Zeichen verwendet werden die in Bezeichnern und Qualifizierungsangaben verboten sind Da die Trennzeichen variieren k nnen sollen sie von jeder Parserimplementierung definiert und bereitgestellt werden Ein Beispiel f r einen Elementpfad in WSDL ist in Tabelle 5 5 aufgef hrt Als Trennzeichen wurden ein Semikolon als Elementtrenner und ein Plus als Trennzeichen zwischen dem qualifizierten Bezeichner des Elements und dem qualifizierten Bezeichner f r den Datentyp gew hlt Der qualifizierende Teil Namensraumangabe im Bezeichner ist durch das Nummernzeichen von dem einfachen Bezeichner getrennt Damit der Pfad ein wenig besser lesbar ist wurde nach jedem Element ein Zeilenumbruch eingef gt 59 5 3 Parser fiir Schnittstellen urn ebay apis eBLBaseComponents GetFeedbackRequest urn ebay apis eBLBaseComponents GetFeedbackRequest turn ebay apis eB LBaseComponents GetFeedbackRequest urn ebay apis eBLBaseComponents GetFeedbackRequest turn ebay apis eB u n Se LBaseComponents GetFeedbackRequestType rn ebay apis eBLBaseComponents UserID turn ebay apis eBLBaseCompone ts Use
33. initListener gt doSetSelection add AllListener removedllListener e doCleanupf Abbildung 6 7 UI Klassen mit Methodennamen keine vollst ndige Methodensignatur 98 6 4 User Interface UI Uber die Methode setSelection bzw doSetSelection wird der Zustand der jeweiligen Komponente gesetzt Diese Methode erh lt als Eingabe ein Objekt das alle Rohdaten beinhaltet die von der Komponente selbst und deren abh ngigen Komponenten ben tigt werden Aus diesem Selection Objekt wird der vollst ndige Zustand der Komponenten hergestellt Abbildung 6 8 zeigt als Beispiel einen Auszug der Klasse DocumentItemList CompositeSelection Sie enth lt die Daten f r den Zustand der Klasse DocumentItemListComposite und deren enthaltenen DocumentItem Composites Es enth lt u a folgende Attribute e documentations Liste der anzuzeigenden Dokumentationsbl cke e addresseeList Liste der f r iDoclt konfigurierten Adressaten e thematicRoleList Liste der f r iDoclt konfigurierten thematischen Rolle e documentationAllowed Flag ob eine Dokumentation f r das selektierte Element erlaubt ist C de akra idocit ui composites DocumentItemListCompositeSelection a documentations List lt Documentation gt o addresseeList List lt Addressee gt o thematicRoleList List lt ThematicRole gt o documentation llowed boolean Abbildung 6 8 Auszug der Klasse DocumentItemListCompositeSele
34. lt alle beschreibenden Attribute f r ein Element aus der allgemeinen Struktur Die Klassen InterfaceArtifact Interface Operation und Parameters enthalten jeweils nur noch Attribute die die Struktur des Elements beschreiben Lediglich die Klasse Parameter hat neben der Liste f r enthaltene Parameter Instanzen complexType noch die Attribute f r einen Datentypen und einen Pfad vom Parameter einer Operation bis zum entsprechenden Attribut Dieser Pfad wird ben tigt da die Dokumentationen von Parametern und deren Attribute in die O Doku integriert wird Beim Einlesen der O Doku werden die 72 6 1 Plattform Core Dokumentationsbl cke anhand dieses Pfades wieder eindeutig den Parametern bzw Attributen der Parameter zugeordnet Alle von SignatureElement erbenden Klassen sind wiederum als abstrakt deklariert Dadurch kann ein Entwickler einer Parser Erweiterung bei der Implementierung besser geleitet werden Er ist gezwungen die Klassen der Struktur zu beerben und durch abstrakte Methoden wird ihm ein Teil der Stellen aufgezeigt die fiir seinen Anwendungsfall implementiert werden miissen Dieses Prinzip wird beispielsweise bei der Erstellung einer tiefen Kopie eines SignatureElements angewandt Eine solche Kopie eines InterfaceArtifacts wird beispielsweise beim Offnen einer Datei angelegt Durch Vergleichen der Tiefenkopie des Initialzustands mit dem aktuellen Zustand kann ermittelt werden ob
35. ndert wurde Beim ffnen der Datei wird sich der aktuelle Stand gemerkt Dieser Stand zusammen mit den in iDocIt gemachten nderungen wird dann einfach in die Datei zur ckgeschrieben und der vorherige Inhalt gel scht auch wenn er ver ndert worden ist Die dritte M glichkeit ist die aus Benutzersicht beste L sung aber aus programmier technischer Sicht die schwierigste und aufwendigste Es m sste ein zeichenweiser oder zeilenweiser Vergleich des neuen Dateistands mit dem alten plus den nderungen erfolgen Wenn z B in einer Zeile beider St nde nderungen gemacht wurden existiert ein Konflikt den der Benutzer per Hand l sen muss Zur Konfliktl sung muss der Benutzer dann entweder diesen direkt in der Datei oder ber eine eigens daf r programmierten grafischen Oberfl che l sen Wenn eine Zeile nur in einem Dateistand ge ndert wurde kann die nderung automatisch bernommen werden Auch wenn die Verschmelzung von Dateist nden die bessere L sung ist ist deren Umsetzung in dieser Bachelorarbeit zu umfangreich Es soll daher die zweite Variante das berschreiben des ggf ge nderten Dateistands mit den Daten aus iDoclt realisiert werden 61 5 4 User Interface UI 5 4 User Interface UI Das User Interface grafische Oberflache soll als Eclipse Editor mit Komponenten aus dem Standard Widget Toolkit SWT von Eclipse implementiert werden Das hat den Vorteil dass es sich in das Konzept und in die Oberflache vo
36. ngige dynamische Softwareplattform die es per Komponentenmodell erm glicht Anwendungen und ihre Dienste Bundles und Services zu modularisieren und zu verwalten Einen gro en Vorteil bietet die M glichkeit Bundles w hrend der Programmlaufzeit hinzuzuf gen zu starten zu stoppen zu aktualisieren und zu entfernen Dadurch ist ein dynamischer Lebenszyklus von Bundles m glich Es geh rt auch ein umfangreicher Abh ngigkeitsmechanismus zu dem Framework Ressourcen von Bundles sind standardm ig nicht nach au en sichtbar Sie m ssen explizit auf Ebene von Java Packages exportiert werden damit andere Bundles diese importieren und nutzen k nnen Durch das statische Importieren werden feste Abh ngigkeiten geschaffen Um die Vorteile der dynamischen Lebenszyklen nutzen zu k nnen importiert man keine Ressourcen sondern fragt von der Service Registry Dienste Java Objekte ab die einen bestimmten Vertrag erf llen bzw ein bestimmtes Interface implementiert haben Ein Bundle kann einen Dienst in der Service Registry 45 Siehe 0 V OSGi Alliance o J 49 5 2 Modularisierung und Erweiterbarkeit anmelden andere Bundles k nnen dann diesen Dienst abfragen und die exportierten Funktionen nutzen Dadurch ist eine lose Kopplung von Bundles m glich Dieses Dienste Konzept ist in Eclipse mit den Extension Points und Extensions realisiert Ein Plugin kann einen Extension Point bereitstellen der typischerweise aus einem Java Inter
37. oder explizit EXPLICIT ist und einer Menge von individuellen Dokumentationen f r verschiedene Adressaten besteht siehe Abbildung 3 1 Schnittstellenelement Dokumentationsblock Dokumentationsblock Dokumentationsblock Erganzende Sichtbarkeitsbereich Thematische Rolle Beschreibung Entwickler Administrator Tester Abbildung 3 1 Aufbau eines Dokumentationsblocks 24 3 3 Dokumentationswerkzeug 3 3 Dokumentationswerkzeug In der Regel enthalten nur Operationsbezeichner ein Verb bei einem Parameter z B ist es eher ungew hnlich Da thematische Rollen nur von einem Verb abgeleitet werden k nnen greift der Ansatz sehr wahrscheinlich nur f r Operationen Aber zur Erleichterung der Dokumentation sollen Elemente aus dem Schnittstellenvertrag die global f r die Schnittstelle gelten z B Ressourcen und Konfigurationen auch global mit einer Menge von den oben beschriebenen Dokumentationsbl cken dokumentiert werden k nnen z B an der Schnittstelle selbst Weiterhin sollen nicht nur die sichtbaren Parameter einer Operation also die Eingaben Ausgaben und Fehler bzw Ausnahmen allgemein dokumentiert werden k nnen sondern auch einzelne Attribute innerhalb der Parameter die von au en erreichbar sind Dadurch sollen thematische Rollen und Dokumentationen direkt einem betreffenden Attribut zugeordnet werden k nnen Die Bedeu
38. private InterfaceModifier interface ExtendsInterfaces abstract InterfaceType InterfaceMemberDeclaration tion InterfaceDeclaration Lp AbstractMethodDeclaration ClassDeclaration Class i faceTyp TypeDeclSpecifier Typ TypeDeclSpecifier Classo iq TypeDeclSpecifier ClassOrInterfaceType Abs Abs Resul a TypeNam trac trac Throws Exception TypeVa tMe tMe tType rn riabl Identifier thodModifier throws Type thodDeclaration Type void ClassType Identifier MethodDeclar Formal LastFo Formal VariableDeclaratorld Type Primi Referenc Parame rmalPa Parame Primi tiveTyp Fe ator terList final rameter a ak ter tiveType TypeNam TypeName ClassType public ExceptionType Identifier final Inter rInterfaceType Identifier faceType te r Identifier AbstractMethodModifier ResultType MethodDeclarator abstract TypeVariable me al FormalParameters Type FormalParameter Ident Ref tifier e byte double ArrayType ClassDeclaration Typ NormalClassD Type 1p 1 eclaration short ClassOrInte ClassModifier class Identi Super renceTyp t i
39. qualifiedIdentifier String SignatureElement parent SignatureElement category String void copy parent SignatureElement SignatureElement creafeSignaturefiement parent SignatureSiement Signatureclement doCopy To signaturefiement Signaturefiement void copyAttributesTo signatureElement SignatureElement void setId id int void Abbildung 5 5 Auszug der abstrakten Klasse SignatureElement BB 00 Ojo o o o co oc Die ID wird ben tigt weil ein SignatureElement allein durch seine Attribute nicht eindeutig in einem InterfaceArtifact ist Dieses Kriterium ist aber beispielsweise f r die Verwaltung von Informationen zu einzelnen SignatureElements au erhalb der Struktur zwingend erforderlich Es k nnen z B in einem InterfaceArtifact zwei verschiedene Interfaces mit gleichen Operations oder in verschiedenen Operations Parameter mit gleichem Typ vorhanden sein In Kapitel 6 1 1 wird darauf genauer eingegangen Die Klassen der Schnittstellenstruktur InterfaceArtifact Interface Operation Parameters und Parameter die von SignatureElement erben sind alle wiederum auch als abstrakt deklariert Dadurch ist ein Entwickler der einen Parser f r das Werkzeug implementieren m chte gezwungen diese Struktur zu beerben Das hat den Vorteil dass durch abstrakte Methoden dem Entwickler deutlicher gezeigt wird welche Teile der Anwendungssituation entsprechend implementiert werden m ssen Ein Beispiel da
40. sie mit der Zugriffsrechteverwaltung f r Bundles bzw Plugins der OSGi Spezifikation auf der Eclipse basiert siehe Kapitel 5 2 1 Wenn iDoclt als Open Source Projekt ver ffentlicht ist sollen Entwickler unabh ngig voneinander z B neue Parser Erweiterungen entwickeln k nnen Da soll die vorgegebene Programmierkonvention der Funktionskapselung in den Komponenten dazu beitragen dass nicht gegenseitig auf Implementierungsdetails zugegriffen wird Beispielsweise soll die Core Komponente oder die Parser Erweiterungen nicht auf grafische Kontrollelemente des Uls zugreifen 48 5 2 Modularisierung und Erweiterbarkeit Da die Komponenten als Eclipse Plugins realisiert werden sollen werden diese zuerst allgemein beschrieben Daraus folgend wird die Modularisierung von den iDocIt Komponenten erl utert und beschrieben wie die Parser Erweiterungen sich an der Plattform Core registrieren 5 2 1 Eclipse Plugins Seit der Version 3 0 basiert Eclipse auf der OSGi Kernspezifikation die in einem eigenen Eclipse Projekt mit dem Namen Equinox zusammen mit einigen zus tzlichen Features z B die Extension Registry entwickelt wird Bevor entschieden wurde dass Eclipse in der Version 3 0 das OSGi Framework nutzen wird war die Idee Eclipse auf eine Plugin Struktur umzustellen Der Name Eclipse Plugin ist bis heute bestehen geblieben gemeint ist aber ein sogenanntes OSGi Bundle Die OSGi Alliance spezifiziert eine hardwareunabh
41. siehe Abbildung 2 4 Searching verbs find search seek get Die thematischen Rollen die man dieser Klasse zuordnen kann w ren beispielsweise AGENT ACTION OBJECT CRITERION SOURCE 19 2 Dokumentation von Operationen mit thematischen Rastern Da viele Verben in unterschiedlichen Kontexten verwendet werden ist es nat rlich auch m glich dass ein Verb gleichzeitig verschiedenen Klassen zugeordnet ist Dann miisste man sich bei der Dokumentation abh ngig von dem verwendeten Kontext fiir eines der definierten thematischen Raster zu dem Verb entscheiden Das Verb get ist ein gutes Beispiel dafiir da es in fast allen Kontexten verwendet werden kann ACTION SOURCE N A IN EA Computing verbs calculate get compute Creating verbs create make get clone generate Searching verbs seek search find get AGENT OBJECT Abbildung 2 4 Beziehungen thematischer Rollen zu Verbklassen Um f r einen Benutzer den Aufwand f r die Definition von thematischen Rastern noch weiter einzuschr nken kann er sich auf die Kontexte und Verben beschr nken die er in seinen Quelltexten verwendet Dadurch entstehen dom nen bzw unternehmensspezifische Raster 20 3 Anforderungsanalyse 3 Anforderungsanalyse In dem vorherigen Kapitel haben wir gesehen wie man eine Operation mit einem thematischen Raster dokumentiert Dafiir ergeben sich bestimmte Anforder
42. 1 1 Motivation Die Kunden der AKRA GmbH verlangen zunehmend die qualitativ hochwertige Dokumentation der zu entwickelnden Software Immer h ufiger ist die Einhaltung von entsprechenden Standards z B IEEE Std 1063 oder ISO IEC 12207 vertraglich festgeschrieben Die AKRA GmbH gew hrleistet dies aktuell haupts chlich durch Schulungen der Mitarbeiter Allerdings bleiben erfahrungsgem weiterhin qualitative Unterschiede der Dokumentation verschiedener Autoren bestehen Um die Erstellung qualitativ hochwertiger Dokumentation zu standardisieren und zu beschleunigen unterst tzt die AKRA GmbH das Promotionsvorhaben von Herrn Krause dem Praxis Referenten dieser Arbeit Herr Krause entwickelt ein Konstruktionsverfahren f r API Dokumentation welches auf Basis des Operationsbezeichners semantische L cken in der Dokumentation identifizieren und bei deren F llung assistieren soll Es fehlt derzeit noch ein implementiertes Werkzeug welches die Mitarbeiter bei der Anwendung dieses Ansatzes unterst tzt Des weiteren plant AKRA sich durch die ffentlichkeitswirksame Pr sentation dieses Werkzeugs in Form eines Open Source Projektes als Innovator im Umfeld der API Dokumentation zu positionieren So will sich die AKRA GmbH einen Wettbewerbsvorteil gegen ber ihren Mitbewerbern im Projektgesch ft verschaffen 4 Vel Reilly Annette D et al IEEE Std 1063 2001 2001 5 Vel 0 V ISO IEC 12207 2008 2008 10 1 2 Ziele und Gang die
43. Benjamin 2009 Prozessorientierte Konstruktion von Benutzeroberfl chen in JavaSPEKTRUM 5 Troisdorf SIGS DATACOM GmbH 2009 S 27 31 Krause Jan Christian 2010 Using Thematic Grids to Document Web Service Operations in Proceedings of the 4th International Conference on Software Engineering Theory and Practice Orlando US ISRST 2010 S 163 170 Krause Jan Christian 2011 Stille und Rauschen in Dokumentation in OBJEKTspektrum 3 noch nicht erschienen Troisdorf SIGS DATACOM GmbH 2011 Martin Robert C 2009 Clean Code A Handbook of Agile Software Craftsmanship Massachusetts US Perentice Hall 2009 Meyer Bertrand 1985 On Formalism in Specifications vol 3 no 1 IEEE Software S 6 25 1985 Reilly Annette D et al 2001 IEEE Std 1063 2001 IEEE Standard for Software User Documentation New York US IEEE 2001 Sebestyen Thomas J 2010 XML Einstieg fiir Anspruchsvolle M nchen Addison Wesley 2010 141 Literaturverzeichnis Socher Rolf 2008 Theoretische Grundlagen der Informatik 3 Miinchen HANSER 2008 o V 2008 ISO IEC 12207 2008 IEEE Std 12207 2008 Systems and software engineering Software life cycle processes 0 0 US IEEE 2008 Z llighoven Heinz 2005 Object Oriented Construction Handbook Developing Application Oriented Software with the Tools and Materials Approach US Dpunkt Verlag und Morgan Kaufmann 2005 Quellen im I
44. D that uniquely identifies a feedback record to be retrieved Used only by the Feedback notification I Thematische Rolle zuordnen Eingabe Thematische F parameter Rolle Dokumentation FeedbackID PRIMARY KEY An ID that uniquely identifies a feedback record to be retrieved Used only by the Feedback notification y Rauschen erkennen Eingabe Thematische parameter Rolle Dokumentation FeedbackID PRIMARY KEY An ID that uniquely identifies a feedback record to be retrieved Used only by the Feedback notification I Rauschen entfernen Eingabe Thematische parameter Rolle Dokumentation FeedbackID PRIMARY KEY Used only by the Feedback notification Abbildung 2 2 Beispielhafte K rzung der Dokumentation f r die Operation Get Feedback aus der eBay Trading API durch Zuordnung thematischer Rollen Abbildung 2 2 zeigt diesen Vorgang beispielhaft Durch die Zuordnung der thematischen Rolle ist eine Redundanz in der O Doku hergestellt worden Der erste Satz hat die gleiche Bedeutung wie die Rolle siehe Markierung in Abbildung 2 2 Da einzelne Schlagw rter f r einen Leser besser zu erfassen sind als ein oder mehrere beschreibende S tze wird der redundante Satz gestrichen und die thematische Rolle bleibt Die Aussage der O Doku hat sich nicht ver ndert ist aber k rzer und besser erfassbar geworden In diesem speziellen Beispiel ist der erste Satz von sich aus schon als Rauschen einzustufen da er den Bezeichner noch einmal
45. Declaration enthalten Klassen und Enumerationen m ssen daher auch von 64 Vgl Gosling James et al Java Language Specification 2005 S 260ff 65 Vgl Anhang C 92 6 3 Parser fiir Java der Parser Erweiterung behandelt werden Deswegen bedeutet es keinen nennenswerten Mehraufwand wenn Klassen und Enumerationen auch direkt mit iDoclIt dokumentiert werden k nnen nicht nur als innere Deklaration InterfaceModifier public protected private abstract static AbstractMethodModifier public abstract ClassModifier public protected private abstract static final MethodModifier public protected private abstract static final synchronized Tabelle 6 9 Auszug der m glichen Modifier der Java Sprachspezifikation in EBNF Bei der Dokumentation von Parametern einer Operation soll sich auf die nach der JavaBeans Spezifikation ffentlich zug nglichen Attributen beschr nkt werden Andere Attribute sollen nicht ber cksichtigt werden D h es sollen nur Attribute ber cksichtigt werden die einen public Getter Lesezugriff oder Setter Schreibzugriff nach dem JavaBeans Design Muster haben Nach diesem Muster muss der Getter f r ein einfaches Attribut mit get beginnen und der Name des Attributs folgen wobei der erste Buchstabe gro geschrieben wird public class EMailAccount public boolean enabled public boolean freeAccount private int id private User u
46. FACHHOCHSCHULE WEDEL BACHELORARBEIT in der Fachrichtung Wirtschaftsinformatik iDoclt Werkzeug zur einheitlichen Dokumentation fur verschiedene Schnittstellenspezifikationen Eingereicht von Dirk Meier Eickhoff SchulstraBe 4 21649 Regesbostel Tel 04165 222 796 Erarbeitet im Abgegeben am Referent FH Wedel Referent Praxis 7 Semester 01 03 2011 Prof Dr Sebastian Iwanowski Fachhochschule Wedel Feldstra e 143 22880 Wedel Tel 04103 80 48 63 Jan Christian Krause AKRA GmbH Domstra e 17 20095 Hamburg Tel 040 309 535 30 Vorwort Ich m chte mich ganz herzlich bei Herrn Prof Dr Sebastian Iwanowski und bei Herrn Jan Christian Krause fiir die sehr gute Betreuung dieser Arbeit bedanken Die kreativen Diskussionen mit Herrn Krause haben mir in sehr vielen Fallen weitergeholfen Ganz besonderer Dank gilt meiner Familie und speziell meiner Frau die w hrend meines Studiums unabl ssig hinter mir standen Ohne ihre Unterst tzung w re mein Studium nicht m glich gewesen Dirk Meier Eickhoff im M rz 2011 Inhaltsverzeichnis PabellenverZercis ii ii 5 O AA isens ros ses riorteeoei o siin 7 PtP UNG id Reese 9 TA IOI A O 9 1 2 Ziele und Gang dieser Untersuehung is a 11 2 Dokumentation von Operationen mit thematischen Rastern mommsmoo o 12 3 Anforderungsanalyse seinen 21 3 1 Allgemeine Schnittstellendokumentation eesserseenseseessnesneennennenne nen 22 A nen ee
47. L PDF u Sie sind dabei aber sehr eng an die M glichkeiten des verwendeten Formats gebunden Die Formate aus der Kategorie 4 sind in ihrer Verwendung flexibler haben aber nicht unbedingt einen direkten Bezug zum Quelltext Bei der wichtigsten untersuchten Funktion der Unterst tzung beim Dokumentieren mit z B einer semantischen Analyse wie es der Ansatz der thematischen Raster macht fallen alle untersuchten Dokumentationssysteme durch Das Hauptaugenmerk liegt bei den sichtbaren Elementen einer Schnittstelle die zur Dokumentation angeboten werden Thematische Rollen die nicht sichtbare Elemente aufzeigen k nnen sind zur Zeit nur durch kreative Leistung des Autors erfassbar Weiterhin sind thematische Rollen adressatenspezifische Beschreibungen und implizite Elemente einer Schnittstelle nur teilweise abbildbar Damit ein Autor von Schnittstellendokumentationen und speziell O Doku technische Unterst tzung beim Dokumentieren erh lt soll das Werkzeug iDoclt entwickelt werden das das Dokumentieren mit thematischen Rastern erlaubt Dadurch soll der kreative Aufwand des Autors und der Dokumentationsumfang reduziert sowie inhaltliche L cken in der O Doku aufgezeigt und so vermieden werden Das Werkzeug soll auch die Erfassung adressatenspezifischer Beschreibungen und die Dokumentation von impliziten Elementen einer Schnittstelle unterst tzen 36 5 Systementwurf 5 Systementwurf Wie sich im vorherigen Kapitel herausgestell
48. Schnittstellen dokumentationen unterst tzen Texteditoren Editoren zur Erstellung von Modellen z B UML u werden hier nicht behandelt 25 Vgl Sebestyen Thomas J XML 2010 S 26ff 21 3 1 Allgemeine Schnittstellendokumentation 3 1 Allgemeine Schnittstellendokumentation Clements et al und auch der IEEE Std 1063 2001 bieten einen umfassenden Katalog an Elementen einer Schnittstelle die dokumentiert werden sollten Es wird auch beschrieben welche Informationen in den Dokumentationen enthalten sein sollten Ein Teil dieses Katalogs der f r den betrachteten Aspekt sinnvoll ist soll als Basisanforderung an Dokumentationsformate und werkzeuge dienen Eine Schnittstelle soll mit Metadaten wie z B einer Versionsnummer und ggf weiteren verwendeten Schnittstellen dokumentiert werden k nnen e Von der Schnittstelle zur Verf gung gestellte Operationen sollen mit ihrer Syntax z B Parameter und Semantik beschrieben werden k nnen Es soll dazu auch dokumentiert werden k nnen was passiert wenn sie verwendet werden mit allen Einschr nkungen bei der Verwendung e Die Dokumentation verwendeter Datentypen soll referenziert werden k nnen e Potentiell auftretende Fehler und Ausnahmen sollen dokumentiert werden k nnen e Vorhandene Konfigurationsm glichkeiten und ihre Auswirkungen sollen dokumentiert werden k nnen e Von der Schnittstelle ben tigte Ressourcen z B Eingabeparameter Dateien od
49. T oder IMPLICIT enthalten Zur Darstellung der adressatenspezifischen Beschreibungen enth lt das lt docpart gt Element eine Menge von lt addressee gt Elementen mit dem string Attribut group das den Adressatennamen enth lt Der in diesem Element enthaltene Text ist die Beschreibung f r diesen Adressaten siehe Tabelle 6 4 52 Vgl Biron Paul V Malhotra Ashok XML Schema Part 2 2001 3 2 Primitive datatypes 78 6 2 Parser fiir WSDL lt wsdl documentation gt lt docpart role xsd string scope EXPLICIT IMPLICIT signatureElement xsd string gt lt addressee group xsd string gt lt addressee gt lt docpart gt lt wsdl documentation gt Tabelle 6 4 lt documentation gt Elementstruktur f r Dokumentation von thematischen Rollen und verschiedenen Adressaten Abbildung 6 2 zeigt im Vergleich dazu die Umsetzung im iDoclt User Interface Dort kann eine thematische Rolle und ein Sichtbarkeitsbereich ausgew hlt sowie eine Menge von adressatenspezifischen Beschreibungen erfasst werden Thematic Role ACTION v Scope EXPLICIT v Analyst Builder Integrater Tester Developer zu Abbildung 6 2 Dokumentationsblock im iDoclt UI 53 Legende Optional 0 bis 1 Mal vorhanden Mehrfach vorhanden 0 bis beliebig oft Alternative von Werten 79 6 2 Parser fiir WSDL 6 2 3 Implementi
50. Type GetFeedbackRequest UserID Type UserIDType 4 Abbildung 6 4 Anzeige der Struktur der Operation Get Feedback aus der eBay Trading API im iDoclt UI Abbildung 6 4 zeigt die Struktur der eBay Trading API fiir die Operationen GetFeedback wie sie in der grafischen Oberfl che von iDoclt angezeigt werden w rde Korrespondierend dazu zeigt die Tabelle 6 7 wohin iDoclt die erfassten Dokumentationen in die WSDL schreibt Die Dokumentation zum PortType 1 und zur Operation 2 werden jeweils direkt in das jeweilige Element geschrieben Die Dokumentationsbl cke der InputMessage 3 und des Elements UserID 4 werden in das lt documentation gt Element des lt input gt Elements geschrieben Die Dokumentation der OutputMessage 5 in das lt output gt Element 85 6 2 Parser fiir WSDL lt wsdl portType name eBayAPIInterface gt lt wsdl documentation gt lt wsdl documentation gt 1 lt wsdl operation name GetFeedback gt lt wsdl documentation gt lt docpart role ACTION scope EXPLICIT gt 2 lt addressee group Developer gt lt addressee gt lt docpart gt lt docpart role FORMUI lt addressee group Deve lt docpart gt lt wsdl documentation gt lt wsdl input message GetFeedbackRequest gt lt wsdl documentation gt lt docpart role Element GetFeedbackRequest gt 3 LA scope IMPLICIT gt 2 loper gt lt addre
51. a ab die i d R auf allen handels blichen PCs lauff hig sind 131 D 2 Installation D 2 Installation Zur Installation von den iDoclt Plugins in Eclipse werden die Dateien e de akra idocit X X X jar e de akra idocit ui_X X X jar e de akra idocit java_X X X jar e de akra idocit wsdl X X X jar in das plugins Verzeichnis der Eclipse Installation kopiert z B C Programme eclipse plugins Das X X X in dem Dateinamen steht f r die Versionsnummer der einzelnen Plugins Danach kann Eclipse gestartet werden und die Plugins werden automatisch erkannt und geladen D 3 Bedienungsanleitung D 3 1 Konfiguration von iDoclt Bevor iDoclt verwendet werden kann m ssen einige Einstellungen get tigt werden ffnen Sie dazu in Eclipse ber Window Preferences iDoclt die Preference Page von iDoclt In dem ersten Fenster der Einstellungen muss der Pfad zum W rterbuch von WordNet 3 0 gesetzt werden sowie zu dem Model des Stanford Part Of Speech Taggers in der Version 3 0 Wenn Sie die beiden Programme noch nicht heruntergeladen haben machen Sie dieses und entpacken die heruntergeladenen Dateien siehe Kapitel D 1 Systemvoraussetzungen 132 D 3 Bedienungsanleitung Geben Sie den Pfad zum Verzeichnis WordNet 3 0 dict in das Feld WordNet Path ein und in das Feld PoS Tagger Model den Pfad zu der Datei left3 words wsj 0 18 tagger an In Abbildung D 1
52. aces Parser eee 55 Abbildung 5 11 Komponentendiagramm der Parser Extension siehe auch Abbildung O Latein 56 Abbildung 5 12 Klassendiagramm des Interfaces Parser mit seinen Kindklassen 57 Abbildung 5 13 Beispielhafte Abbildung einer WSDL 1 1 Struktur in die allgemeine Schnittstellenstruk iii ade 58 Abbildung 5 14 Layoutentwurf des User Interfaces ooooonnonnnnccnnnccooccconnconnccconnnnnos 63 Abbildung 5 15 Beispiel fiir die Ermittlung von zugeordneten thematischen Rollen A E EE A A A At ia 65 Abbildung 5 16 Klassendiagramm der UI Komponenten eenenersnen 65 Abbildung 5 17 Aktivit ten beim Start von Eclipse enennneene 66 Abbildung 5 18 Ablauf der Methodenaufrufe beim ffnen einer Datei in iDoclt 67 Abbildung 5 19 Aktivit tsdiagramm zum Funktionsablauf wenn ein Benutzer ein Signaturelement im UI selektiert 68 Abbildung 5 20 Ablauf der Methodenaufrufe beim Speichern von Anderungen 69 Abbildung 6 1 Beispiel der Wiederverwendung des Datentyps Customer 71 Abbildung 6 2 Dokumentationsblock im iDoclt UI 79 Abbildung 6 3 Klassen der allgemeinen Schnittstellenstruktur fiir WSDL 83 Abbildung 6 4 Anzeige der Struktur der Operation GetFeedback aus der eBay Trading API im U O 85 Abbildung 6 5 Javadoc Beispiel in HTML mit iDoclt Dokumentationsbl cken 91 Abbildung 6 6 Klassen der allgemeinen Schnittstellenstruktur fiir Java
53. ach die nderungen berschrieben werden sollte verbessert werden Das Formatierungsproblem betrifft auch beide Parser Erweiterungen Eclipse bietet zwar einen automatischen Formatierer an den iDoclt verwenden k nnte aber wenn ein Entwickler diesen nicht benutzt w rden seine ganzen h ndischen Formatierungen ge ndert werden Daf r sollte noch eine bessere L sung gefunden werden Bereits vorhandene Dokumentationen werden vom Prototypen bisher ignoriert und berschrieben Wenn das Werkzeug in der Praxis eingesetzt werden sollte ist aber davon auszugehen dass bereits Dokumentation vorhanden ist Deswegen muss ein Weg gefunden werden die vorhandene Dokumentation durch eine Standardzuordnung in die Struktur von iDoclt zu berf hren Das gr te Problem stellt aber WSDL4J dar indem es nur eine feste Menge von Attributen unterst tzt Dieser Mangel muss auf jeden Fall behoben werden bevor iDoclt in der Praxis eingesetzt wird 7 4 Fazit In dem Fallbeispiel wurde sehr sch n sichtbar wie iDoclt dem Autor mit den thematischen Rastern einen Leitfaden an die Hand gibt der zeigt was alles dokumentiert werden sollte Dieser Leitfaden steht immer zur Verf gung unabh ngig wie umfangreich die Methodensignatur ist Anzahl der sichtbaren Elemente Daran kann sich der Autor entlanghangeln und St ck f r St ck die Schnittstelle vollst ndig dokumentieren Durch die thematischen Rollen wird ihm aufgezeigt worauf er seine Aufmer
54. aderDoc Ja Nein 9 Nein Help Generator Nein Nein 4 Nein Imagix 4D Ja Nein 2 Nein Javadoc Ja Nein 1 Nein Natural Docs Teilweise Nein 19 Ja RDoc Nein Nein 1 Nein ROBODoc Ja Nein 15 Ja TwinText Ja Nein 25 Ja Universal Report Ja Nein 25 Ja VSdocman Nein Nein 2 Nein YARD Nein Nein 1 Nein Tabelle A 5 Unterstiitzte Programmier und Beschreibungssprachen von den untersuchten Dokumentationssystemen 124 A Auswahl existierender Dokumentationssysteme Name URL CppDoc http www cppdoc com DITA http dita xml org Doc O Matic http www doc o matic com DOC http docpp sourceforge net DocBook http www docbook org Document X http www innovasys com products dx2010 overview aspx Doxygen http www doxygen org GenHelp http www frasersoft net genhelp HeaderDoc http developer apple com library mac documentation DeveloperTools Concept ual HeaderDoc intro intro html Help Generator http www helpgenerator com Imagix 4D http www imagix com Javadoc http www oracle com technetwork java javase documentation index jsp 135444 html Natural Docs http www naturaldocs org RDoc http rdoc sourceforge net ROBODoc http www xs4all nl rfsber Robo robodoc html TwinText http www ptlogica com TwinText Universal Report http www omegacomputer com VSdocman http www helixoft com vsdocman overview html YARD http yardoc org Tabelle
55. atischen Rastern In Tabelle 2 1 ist die Dokumentation zur Operation GetFeedback auszugsweise abgebildet Fiir die vier Eingabeparameter ist auch jeweils der erste Satz der Dokumentation aufgef hrt um zu zeigen dass die Bezeichner noch einmal in Prosa wiedergegeben wurden was eine Art von Rauschen ist In Abbildung 2 1 wird dieses am Beispiel des Parameters ItemID gezeigt GetFeedback ItemID The ID of the item that you want feedback data about Abbildung 2 1 Rauschen in der O Doku am Beispiel des Eingabeparameters ItemID der Operation Get Feedback aus der eBay Trading API Die in Abbildung 2 1 gezeigte Beschreibung enth lt keine neuen Informationen denn der Bezeichner selbst ItemID sagt dass es die ID eines Artikels ist und der Operationsbezeichner Get Feedback besagt dass die Bewertung abgerufen werden soll Weiterhin impliziert die ID im Bezeichner eine eindeutige Identifikation eines Benutzers Die Beschreibung ist also unn tig Ein Kommentar soll tiber diese Worte hinausgehen und dem Leser Informationen offenbaren die nicht sofort erkennbar sind Es soll keine unn tigen Informationen enthalten gt Um das Problem der Stille und des Rauschens anzugehen wird ein neuer Dokumentationsansatz zur Erstellung von O Doku verwendet Dabei handelt es sich um eine verbbasierte Analyse von Operationsbezeichnern mit Ableitung von thematischen Rastern die aus der Linguistik
56. auszugsweise in der EBNF aufgef hrt Es sind nicht alle Elemente der Spezifikation in dem Auszug enthalten und die Produktionen werden teils nicht vollst ndig bis zum Terminalsymbol aufgef hrt Die gro geschriebenen W rter z B InterfaceDeclaration und Identifier stellen Nichtterminalsymbole und die klein geschriebenen W rter z B Long und public sowie die Zeichen in einfachen Hochkommata z B und stellen cc Terminalsymbole dar Ein vertikaler Strich trennt Alternativen mit eckigen Klammern eingeschlossene Symbole sind optional ein oder keinmal vorhanden und mit geschweiften Klammern eingeschlossene Symbole k nnen null bis beliebig oft wiederholt werden Legende a Terminalsymbol Zeichen in einfachen Hochkommata symbolName Terminalsymbol klein geschriebene W rter SymbolName Nichtterminalsymbole gro geschriebene W rter Optionale Symbole ein oder keinmal vorhanden an Optionale Wiederholung von Symbolen null bis beliebig oft nalas Alternative Symbole 128 C Java Interface Deklaration In No In je X TOn ter terfaceDeclaration dsInt rmalInterfaceDeclaration terfaceModifier public Identifier InterfaceBody protected static faces E faceBody xt nds InterfaceType a Inter Inter fac MemberDeclara NormallnterfaceDeclaration
57. ch aus vor HeaderDoc bietet z B das Schl sselwort dependency zur Beschreibung von Ressourcen von denen die Schnittstelle abh ngt und ROBODoc bietet das Schl sselwort SIDE EFFECTS an um Seiteneffekte zu beschreiben Das ist aber jeweils nur ein von mehreren nicht sichtbaren Elementen die beschrieben werden sollen Aber alle um weitere 33 Legende ist vorgesehen nicht m glich o nicht vorgesehen aber m glich 32 4 2 Unterstiitzung der Dokumentation mit thematischen Rollen Schl sselw rter erweiterbaren Formate k nnen dahingehend angepasst werden nicht sichtbare Elemente zu unterst tzen Das gilt auch f r die adressatenspezifischen Beschreibungen die kein Dokumentationssystem vorsieht Unterst tzte Dokumentationstypisierungen Untypisierter Zielgruppen Bereich gerichtete Erweiterbar Name Referenz Beschreibung Freitext Beschreibung um Typen CppDoc Doc O Matic o DOC eb Document X E o Doxygen o GenHelp F o HeaderDoc o Javadoc o o Natural Docs o ROBODoc F o TwinText 7 z z VSdocman O YARD ag o DITA o o o o o DocBook o o o o o Tabelle 4 2 Fortsetzung Unterst tzte Dokumentationstypisierungen von den untersuchten Kategorie 3 und 4 Dokumentationssystemen Zum anderen wird f r nicht sichtbare Elemente gepr ft ob d
58. chen Raster gut funktionieren muss daraufhin eine Schnittstelle entwickelt werden Jede Operation sollte eine starke Koh sion haben D h sie sollte genau eine wohldefinierte Aufgabe haben F r eine wohldefinierte Aufgabe kann dann ein pr zises Verb verwendet werden Wenn immer dasselbe Verb z B to get verwendet wird oder eine Operation mehrere Funktionen abdeckt kann der Vorteil der thematischen Raster wieder zunichte gemacht werden Entwickler aber auch Autoren miissen dahingehend geschult werden dass sie den Dokumentationsansatz mit thematischen Rollen umsetzen k nnen und verinnerlichen Das Arbeiten nach dem Ansatz ist nicht intuitiv m glich das Konzept muss dazu verstanden worden sein 114 7 4 Fazit Durch das Zuordnen von thematischen Rollen kann ein Element auch bereits ausreichend dokumentiert sein wodurch ein beschreibender Text entf llt siehe Kapitel 2 Dadurch kann eine Dokumentation gek rzt werden und auch Rauschen in der Dokumentation vermieden werden Die Navigation zu den einzelnen Schnittstellenelementen in dem iDoclt Editor ist in dem aktuellen Prototypen viel Klickarbeit Jede Methode jeder Parameter und auch deren Attribute m ssen einzeln in dem Navigationsbaum angeklickt werden um dann Dokumentationsbl cke hinzuf gen zu k nnen Auch die gespeicherte Dokumentation ist auf den ersten Blick umfangreicher Das liegt aber haupts chlich daran dass auch mehr dokumentiert wird als vorher
59. cht sollen in der O Doku bereits verwendete Rollen eine Kennzeichnung erhalten Diese Komponente soll keine weitere Funktionalit t erhalten die ber das Anzeigen von den thematischen Rastern hinausgeht Bereits zugeordnete thematische Rollen f r eine Operation sollen in der Dokumentation aller Elemente der Operation gesucht werden als auch in den Dokumentationen der Elemente auf direktem Weg hoch zum Wurzelelement der Struktur dem InterfaceArtifact Zu den Elementen einer Operation z hlen seine Eingaben Ausgaben Ausnahmen und wiederum jeweils den Attributen ihrer Datentypen In der beispielhaften Schnittstellenstruktur aus Abbildung 5 15 w rden f r die Methode getFeedback in allen Dokumentationen der zur Methode geh renden Elemente gesucht werden Dazu geh ren die Methode selbst und alle Ausnahmen 64 5 4 User Interface UI und der Ergebnistyp Auf dem Weg bis zum Wurzelelement wiirden noch die Dokumentationen des Elements Get FeedbackCall und die Dokumentationen des Wurzelelements GetFeedbackCall java nach bereits zugeordneten Rollen durchsucht werden Select Signature Element GetFeedbackCall java Artifact S GetFeedbackcall Class H GetFeedbackCall Constructor getFeedback Method ReturnType f Throws ApiException Type ApiException SdkException Type SdkException Exception Type Exception Abbildung 5 15 Beispiel f r die Erm
60. ction Das Selection Objekt beinhaltet immer den aktuellen Zustand einer Komponente Es wird in der jeweiligen Komponente zwischengespeichert und wenn eine Anderung eintritt wird es ge ndert und das ChangeEvent fireChangeEvent ausgel st Die Komponenten die einen Listener bei der feuernden Komponente registriert haben rufen dann das ge ndert Selection Objekt ab und ndern danach entsprechend selbst ihren Zustand und den der abh ngigen Komponenten Danach wird wieder ChangeEvent fireChangeEvent gefeuert damit die dar ber liegenden Komponenten ber die nderung informiert werden usw 99 6 4 User Interface UI Dieses Prinzip soll beispielhaft an den Komponenten DocumentItemList Composite und DocumentItemComposite gezeigt werden Das Selection Objekt des DocumentItemListComposites enth lt u a eine Liste von Documentation Objekten die in dem Document ItemListComposite dargestellt werden sollen Das DocumentItemListComposite selbst besitzt eine Liste von DocumentItemComposites und eine Liste von Schaltfl chen ber die ein DocumentItemListComposite aus der Liste entfernt werden kann sowie eine eine Schaltfl che zum Hinzuf gen weiterer Dokumentationen Die beiden genannten Listen sind immer synchron gehalten F r jedes DocumentItemComposite gibt es an der gleichen Stelle der Liste eine Schaltfl che ber die das Composite entfernt werden kann Wenn au
61. d auch um weitere Schl sselw rter erweiterbar weswegen teilweise fehlende Schl sselw rter individuell nachgepflegt werden k nnen Die Anforderungen von Clements et al an eine Schnittstellendokumentation scheinen auch in der Praxis verbreitet erkannt und angewendet zu werden 31 4 2 Unterstiitzung der Dokumentation mit thematischen Rollen Unterst tzte Dokumentationstypisierungen Seit welcher Version Name Eingabe Ausgabe Fehler Autor Version enthalten Veraltet CppDoc T Doc O Matic DOC Document X Doxygen a GenHelp HeaderDoc Javadoc Natural Docs ROBODoc TwinText VSdocman YARD DITA o 1 o o o o o o DocBook o o o o o o o Tabelle 4 1 Unterst tzte Dokumentationstypisierungen von den untersuchten Kategorie 3 und 4 Dokumentationssystemen F r nicht sichtbare Elemente gibt es zwei Kriterien die gepr ft werden siehe Tabelle 4 3 Zum einen ob diese abbildbar sind d h ob Schl sselw rter zur Beschreibung dieser Elemente vorgesehen sind die nicht direkt an der Schnittstelle sichtbar sind aber Vertragsbestandteil sind Bei Operationen fallen darunter z B implizit verwendete Ressourcen Seiteneffekte und Attribute aus den inneren Strukturen von Parametern Nur zwei von den 19 Referenzsystemen sehen so eine Beschreibung von si
62. der in der von Parameters erbenden Klasse WSDLMessage entsprechend implementiert werden Wenn das erledigt ist werden auch die Attribute und somit alle Nachfolger der Klasse Parameters kopiert public abstract class Parameters extends SignatureElement Override public final SignatureElement copy SignatureElement parent SignatureElement newElement super copy parent Parameters newParameters Parameters newElement for Parameter param this parameters paramList addParameter Parameter param copy newParameters return newParameters Tabelle 6 1 Auszug der Klasse Parameters public abstract class SignatureElement public SignatureElement copy SignatureElement parent SignatureElement newSigElem createSignatureElement parent copyAttributesTo newSigElem doCopyTo newSigElem return newSigElem Tabelle 6 2 Auszug der Klasse SignatureElement 74 6 1 Plattform Core public class WSDLMessage extends Parameters Override protected SignatureElement createSignatureElement SignatureElement parent return new WSDLMessage parent super getCategory Override protected void doCopyTo SignatureElement signatureElement WSDLMessage wsdlMessage WSDLMessage signatureElement copy attributes to wsdlMessage Tabelle 6 3 Au
63. der kann der Parser von JaxMeJS keine Kommentare aus der Quelldatei einlesen Daher ist er f r iDocIt unbrauchbar Die API des javaparsers hat einen gleichwertigen Funktionsumfang wie die von JaxMeJS Aber im Gegensatz zu JaxMeJS kann er auch zu den Elementen einer Java Quelle z B Interfaces Klassen Methoden und Attribute die Javadoc Kommentare einlesen Aber auBer das jeweils dazugeh rige Javadoc werden keine weiteren Kommentare beriicksichtigt Beispielsweise w rden keine normalen Kommentare die zwischen Methoden geschrieben sind beriicksichtigt werden Diese wiirden nach dem Speichern der Struktur gel scht sein was nach der eingangs geforderten Pr misse nicht passieren darf Die JDT werden auch in Eclipse f r den Java Editor eingesetzt Sie parsen eine Java Quelldatei vollst ndig Jedes Element kann in dem entstandenen abstrakten Syntaxbaum ASB manipuliert oder entfernt werden aber es k nnen auch neue Elemente hinzugef gt werden Zu den Elementen geh ren auch Javadoc und normale Kommentare Der ASB bietet auch die M glichkeit an durch Reflection weitere Informationen ber die einzelnen Elemente zu erhalten z B Struktur Attribute der Datentypen Das Speichern des ASBs wird auf Befehl von den JDT bernommen 58 Vgl 0 V JaxMeJS o J 59 Vgl 0 V javaparser o J 60 Vgl 0 V Java development tools JDT Core o J 88 6 3 Parser fiir Java Die JDT bieten die beste Unterstiitzung fiir das Vorhabe
64. dung 7 5 zeigt im UI von iDoclt einige realisierte Anforderungen In der grafischen Oberfl che die sich in Eclipse integriert k nnen die Schnittstellenelemente die Attribute von Parametertypen und nicht sichtbare Elemente z B eine Berechnungsvorschrift oder qualitative Eigenschaften mit beliebig vielen Dokumentationsbl cken dokumentiert werden Ein Dokumentations 111 7 2 Realisierung der Anforderungen block besteht dabei aus einer thematischen Rolle einem Sichtbarkeitsbereich und einer Menge von adressatenspezifischen Beschreibungen Wenn ein Element einer Operation selektiert wird wird das Verb vom Operationsbezeichner extrahiert und die dazugeh rigen thematischen Raster angezeigt Select Signature Element Document Signature Element getFeedback Me El GetFeedbackCall java Artifact Dokumentierbare Add Thematic Ro ea Ai S 0 GetFeedbackCall Class Elemente z Dokumentationen 0 GetFeedbackCall Constructor K 7 Thematic Role ACT ION i a Scope EXPLICIT Mil E 0 getFeedback Method z Developer an sw Eiretumtype Analyst Builder Integrater Tester Developer e 5 thr ows Retrieves the accumulated Feedback left for a specified user or the ql summary Feedback data for a specific transaction or item ApiException Type ApiException sdkException Type SdkException Exception Type Exception getUs
65. e Beschreibung dieser Rolle erfasst werden Die Namen der thematischen Rollen sollten einheitlich in Gro buchstaben geschrieben sein Preferences Thematic Roles General Help Defined Thematic Roles Edit selected Thematic Role iDocIt Defined Items Name ACTION Addressees OBJECT vont F Thematic Grids LOCATION performe Thematic Roles AGENT y the component Install Update SOURCE J ACTION en FORMULA JavaScript OPERAND CRITERION PRIMARY KEY Add Item Remove selected Item s Restore Defaults Apply Abbildung D 4 iDoclt Preference Page f r thematische Rollen Description D 3 2 Erstellen von Dokumentationen Wenn eine Dokumentation f r eine Schnittstelle erfasst werden soll wird der iDoclt Editor ber das Kontextmen der entsprechenden Datei in Eclipse ge ffnet In dem Kontextmen klicken Sie dann auf Open With und w hlen dann iDoclt Wenn der Eintrag iDoclt nicht in der ersten Liste sein sollte w hlen Sie Other und dann aus der Liste iDoclt Falls der Eintrag auch dort nicht vorhanden sein sollte ist das iDoclt Plugin nicht korrekt installiert 135 D 3 Bedienungsanleitung Schlie en Sie dann Eclipse kopieren die jar Dateien noch einmal in das plugins Verzeichnis der Eclipse Installation und starten Eclipse erneut siehe D 2 Installation Wenn der iDoclt Editor ausgew hlt werden kann wird von iDoclt gepr f
66. e Schnittstellenstruktur f r WSDL siehe Kapitel 6 2 3 und Java siehe Kapitel 6 3 3 vorgestellt Die Klasse ParserImplementation verwendet u a die Klasse InterfaceParser die daf r zust ndig ist einen Quelltext in die allgemeine Struktur zu berf hren Sie soll dazu den Quelltext parsen und nach einer vorher definierten Abbildung einzelne Elemente den Elementen in der allgemeinen Struktur zuordnen und so ein InterfaceArtifact aufbauen siehe Abbildung 5 13 Beim Parsen wird auch jeweils der vorhandene Kommentarblock von einem 57 5 3 Parser fiir Schnittstellen Quelltextelement eingelesen und von dem verwendeten DocumentationParser in eine Liste von Documentation s zerlegt und dem zugeh rigen SignatureElement angeh ngt Definitions Operation Input Message Output Message Fault Message B Parameter lt P InterfaceArtifact Interface Y Operation J _ A gt Input Parameters N A Pom oy gt Parameter lt p y Output Parameters _ Parameter Parameter aa Exception gt Message Y N i bi Parameter D gt Parameter 4 Abbildung 5 13 Beispielhafte Abbildung einer WSDL 1 1 Struktur in die allgemeine Schnittstellenstruktur Wenn ein I
67. e eine Beschreibung eine kommaseparierte Liste von Verben die diesem Raster zugeordnet sind und eine Menge von thematischen Rollen die in dem Raster enthalten sein sollen Die thematischen Rollen die diesem Raster zugeordnet sein sollen werden mit einem Haken markiert Diese werden dann in der iDoclt Oberfl che als empfohlene thematische Rollen fiir die zugeordneten Verben angezeigt Preferences Thematic Grids nr E General Help Defined Thematic Grids Edit selected Thematic Grid Doclt Defined Items Name Addressees Calculating Operations Calculating Operations Thematic Grids Searching Operations Thematic Roles Description Install Update Java Operations calculating sth JavaScript Verbs seperate verbs with commas Plug in Development Run Debug calculate compute Associated Thematic Roles C OBJECT C PURPOSE C LOCATION AGENT SOURCE ACTION C DURATION FORMULA OPERAND C CRITERION Add Item Remove selected Item s Ol PRIMARY KEY Restore Defaults Apply Abbildung D 3 iDoclt Preference Page f r thematische Raster 134 D 3 Bedienungsanleitung Die thematischen Rollen die fiir die thematischen Raster ausgew hlt werden k nnen werden in der Preference Page fiir thematische Rollen siehe Abbildung D 4 verwaltet Dort k nnen sie hinzugef gt und gel scht werden Zu einer thematischen Rolle kann ein Name und ein
68. einzuteilen Architekt Ein Architekt ist an der Wiederverwendbarkeit der Variabilit t der pr zisen Semantik und den Qualit tseigenschaften von Komponenten z B Schnittstellen und deren Operationen interessiert Weiterhin ben tigt er ein Basisverst ndnis von der Implementierungsweise Administrator Ein Administrator baut ein System aus seinen Bestandteilen zusammen und hat ein besonderes Interesse an das Zusammenspiel der Komponenten Tester Ein Tester ben tigt detaillierte Informationen ber alle Operationen Ressourcen und Funktionalit ten damit er aussagekr ftige und vollst ndige Tests entwickeln kann Tabelle 3 1 Auswahl an m glichen Adressaten 28 Vgl Clements Paul et al Documenting Software Architectures 2008 S 237ff 23 3 2 Format Es sollen auch nicht nur explizite Signaturelemente einer Operation sondern auch implizite Elemente dokumentiert und ausgezeichnet werden k nnen Ein explizites Element einer Signatur ist ein an der Signatur sichtbares Element wie z B Ein und Ausgabeparameter Ein implizites Element ist demnach ein an der Signatur nicht sichtbares Element das aber trotzdem zum Vertrag der Schnittstelle bzw Operation geh rt Dies kann z B eine Formel oder eine nicht als Parameter tibergebene aber verwendete Datenquelle sein Daraus ergibt sich dass ein Dokumentationsblock aus einer thematischen Rolle einem Sichtbarkeitsbereich Scope der implizit IMPLICIT
69. er xsd boolean Die geschweiften Klammern bedeuten dass die darin enthaltenen Elemente null bis beliebig oft wiederholt werden also eine Menge bilden Dies kann auch die leere Menge sein Wenn mehrere Elemente hintereinander aufgef hrt sind definieren sie eine Folge Sie werden alle aus dem linken Nichtterminal abgeleitet soweit keine weiteren Optionen vorhanden sind Ein vertikaler Strich definiert alternative Resultate der Produktionsregel Die runden Klammern bilden eine Gruppe von Symbolen Alternativen innerhalb der Gruppe beziehen sich ausschlie lich auf die Symbole innerhalb der runden Klammern 44 5 1 Grammatiken InterfaceArtifact Interface Attributes Interface Operation Interface Attributes Operation InputParameter OutputParameter Exception Attributes InputParameter Parameters OutputParameter Parameters Exception Parameters Parameters Parameter Attributes Parameter ComplexType SimpleType Attributes ComplexType Parameter Attributes Identifier Documentations Documentations Documentation Documentation Role Scope Addressee Doc Role String Scope explicit implicit Addressee Doc Addressee String Addressee Name Name String Tabelle 5 3 Allgemeine Grammatik einer Schnittstellenstruktur in EBNF vereinfachte Darstellung Aus der allgemeinen Grammatik kann dann eine Klassenstruktur abgeleitet werden
70. er ndern bei der WSDL nicht den Programmcode da sie auf XML basiert Eine Ver nderung des Formats ist demnach nicht entscheidend aber sie sollte trotzdem bestm glich vermieden werden In z B einer Versionskontrolle sollen bei einem Dateivergleich nur die wichtigen nderungen ber cksichtigt werden Unn tige Format nderungen sollen diese nicht berlagern und auch nicht zu unn tig vielen Datei nderungen f hren Von der Parser Erweiterung werden nur bestimmte Teile der WSDL Elemente aus der allgemeinen Schnittstellenstruktur zugeordnet Die restlichen Teile m ssen aber trotzdem eingelesen und behandelt werden damit die Datei vollst ndig geschrieben werden kann Nicht zugeordnet werden z B das lt service gt und lt binding gt Element in einer WSDL Datei Um den Entwicklungs und Implementierungsaufwand f r einen vollst ndigen Parser f r WSDL mit zur ckschreiben der Daten zu vermeiden wird auf einen existierenden Parser zur ckgegriffen Zun chst werden einige existierende Parser evaluiert ob deren Funktionalit t f r den Zweck WSDL zu parsen und zu speichern ausreicht Daran folgend wird die XML Struktur der Dokumentationen von iDoclt entwickelt wie sie in der WSDL im lt documentation gt Element gespeichert werden soll Zum Schluss werden einige Details zur Implementierung beschrieben 76 6 2 Parser fiir WSDL 6 2 1 Existierende XML WSDL Parser Da die WSDL auf XML basiert k nnen XML Parser verwendet
71. er und Beschreibungssprache eine eigene Parser Erweiterung als Eclipse Plugin geben soll In diesem Kapitel wird diese Komponente siehe Abbildung 5 11 mit ihrer allgemeinen Funktionalit t detaillierter beschrieben lt lt component gt gt Parser Extension lt lt component gt gt lt lt class gt gt Extended Interface Artifact Structure Parserlmplementation use use lt lt class gt gt lt lt class gt gt InterfaceGenerator InterfaceParser 1 1 use lt lt class gt gt lt lt class gt gt DocumentationGenerator DocumentationParser Abbildung 5 11 Komponentendiagramm der Parser Extension siehe auch Abbildung 5 6 Damit sich die Parser Extension Komponente an dem Extension Point der Core Komponente registrieren kann muss sie seinen Vertrag erf llen Dazu wird das Parser Interface in der Klasse ParserImplementation realisiert In Abbildung 5 12 sind die Parserimplementierungen f r Java und WSDL exemplarisch aufgef hrt Einige XML Angaben miissen von der Extension auch bereitgestellt werden Es muss das Interface von dem Extension Point angegeben werden und welche Klasse in der Extension dieses Interface implementiert siehe Tabelle 5 4 56 5 3 Parser fiir Schnittstellen O de akra idocit extensions Parser de akra idocit java services JavaParser de akra idocit wsdl services WSDLParser o SUPPORTED TYPE String o SUPPORTED_TYPE String delimiters Delimiters o delimiters Del
72. er Datenbankverbindungen sollen wie die von ihr zur Verf gung gestellten Operationen in ihrer Syntax Semantik Verwendung und Einschr nkungen dokumentiert oder referenziert werden k nnen 26 Vgl Clements Paul et al Documenting Software Architectures 2008 S 228 237 27 Vel Reilly Annette D et al IEEE Std 1063 2001 2001 S Sff 22 3 2 Format 3 2 Format Damit thematische Rollen in einer Dokumentation beschrieben werden k nnen m ssen sie darin durch ein Schl sselwort ausgezeichnet werden k nnen Ein Format muss daher eine Auszeichnungsweise daf r anbieten Es wurde auch festgestellt dass nicht jede Rolle und somit jede Dokumentation f r jeden Leser interessant ist und weiterhin unterscheiden sich die gew nschten Detailgrade der Dokumentation f r unterschiedliche Leser z B zwischen Entwicklern und Systemarchitekten Das macht eine Unterteilung in adressatenspezifische Beschreibungen n tig Eine m gliche Auswahl an Adressaten ist in Tabelle 3 1 gezeigt Adressat Beschreibung Entwickler Ein Entwickler ben tigt detaillierte Informationen ber die Nutzungsweise und Semantik von Operationen deren Parameter und Resultate Manager Manager ben tigen die Dokumentation f r Planungszwecke Sie brauchen nur eine hoch aggregierte Beschreibung der Funktionalit t und Metriken um Komplexit t messen zu k nnen um so Sch tzungen f r z B Entwicklungszeit zu treffen und auch geeignetes Personal
73. er ist f r diese Elemente auch kein Platz f r eine Dokumentation als Javadoc in einer Java Quelldatei vorgesehen Es macht dann keinen Sinn f r diese Elemente Dokumentationen in dem UI zu erfassen 95 6 3 Parser fiir Java Wie bereits erw hnt wird die Dokumentation der JavaParameter mit in die der zugeh rigen Methode integriert Dazu miissen die einzelnen Dokumentationen wieder einen eindeutigen Pfad zur Identifikation des Elements enthalten Der Pfad beginnt aber nicht mit der Klasse JavaParameters wie bei der WSDL sondern mit der Klasse Parameter Als Trennzeichen f r den Attributpfad sollen ein Schr gstrich als Elementtrenner ein Doppelpunkt als Trennzeichen zwischen dem Datentyp und dem voll qualifizierten Bezeichner und ein Punkt als Trennzeichen zwischen dem Bezeichner und der Namensraumbezeichnung Java Paket verwendet werden Alle drei Zeichen sind laut Spezifikation in einem Bezeichner nicht erlaubt Der Punkt als Namensraumtrenner wird daf r bereits von Java verwendet Von iDoclt wird dieses nach der Definition gehandhabt dass in einem qualifizierten Bezeichner der Bezeichner nach dem letzten Punkt der einfache Name des Elements ist Beim Einlesen eines Javadoc Kommentarblocks soll der Prototyp von iDoclt erst einmal nur Beschreibungen ber cksichtigen die im iDoclt Format vorliegen Andere Beschreibungen werden ignoriert und beim erneuten Speichern der Dokumentation berschrieben In einer folge
74. erID Method Thematische Rolle Sichtbarkeitsbereich 2 0 setUserID Method 1 i EE Parameters gt userID Type String h el Impucrr y getltemID Method y Thematic Role FORMULA 5 Scope IMPLICIT i lt uu ae gt Analyst Builder Integrater Tester Developer SM Overview of recommended roles For getFeedback Method Lock at http pages ebay comfhelp feedback howitworks html Calculation verbs A ACTION Associated 3 3 AGENT Associated Aus dem Verb abgeleitete FORMULA Associated th ematische Raster OBJECT Associated T SOURCE v Abbildung 7 5 Realisierte Anforderungen im UI Die im UI erfassten Dokumentationen werden dann direkt in die ge ffnete Datei gespeichert Die Erweiterbarkeit um unterst tzte Programmier und Beschreibungs sprachen ist mit dem Eclipse Konzept der Extension Points und Extensions umgesetzt Die Anforderungen der AKRA GmbH siehe Kapitel 3 4 werden auch erf llt Sie fordert dass iDoclt sich in Eclipse integrieren soll und dass es Java Quellen sowie WSDL Dateien dokumentieren kann 7 3 Probleme des Prototypen Wie in den Implementierungskapiteln beschrieben sind die Parser Erweiterungen f r Java und WSDL noch nicht hundertprozentig ausgereift Zum einen haben beide Parser das Problem mit nderungen der Datei die auftreten wenn iDoclt gerade 112 7 3 Probleme des Prototypen ge ffnet ist Die momentane L sung dass einf
75. erung Dem Editor wird u a die Eclipse Dateiressource Datentyp IFile bergeben die er an den PersistenceService weitergibt um die Datei parsen zu lassen Der PersistenceService fragt zuerst von Eclipse die angemeldeten Extensions f r das Parser Interface ab Wenn eine Parser Extension f r den bergebenen Dateityp vorhanden ist Pr fung auf Dateiendung wird das IFile weiter an den Parser gegeben Der Parser parst die Datei und berf hrt die Struktur in die allgemeine Schnittstellenstruktur Das erstellte InterfaceArtifact wird dann an den PersistenceService zur ckgegeben Der PersistenceService gibt das Objekt weiter an den DocumentationEditor in dem dann das 67 5 5 Kommunikation der Plattform Services EditArtifactDocumentationComposite mit seinen Komponenten initialisiert wird Danach wird das Editorfenster in Eclipse angezeigt Klick auf Signaturelement in iDoclt UI Benutzer Kein Element einer Operation Element Zeige vorhandene einer Liste von thematischen Rastern Dokumentations bl cke Operation Ermittle Operations Ermittle bereits Zeige thematische bezeichner zugeordnete Raster thematische Rollen Operationsbezeichner Liste von thematischen Rastern 5 e Q Extrahiere Leite thematische Verb Raster ab iDoclt Core Abbildung 5 19 Aktivit tsdiagramm zum Funktionsablauf wenn ein Benutzer ein Signaturelement im UI selektiert Nun kann der Benut
76. erungsdetails des WSDL Parsers WSDL4J in der aktuellen Version 1 6 2 unterst tzt nur die WSDL 1 1 Spezifikation Das ist aber fiir den Rahmen dieser Bachelorarbeit ausreichend da nur die Unterstiitzung von WSDL 1 1 gefordert ist Bei der Arbeit mit WSDL4J haben sich aber drei M ngel herausgestellt 1 Mangel Zum einen ein nicht so gravierender Mangel dass die Formatierungen z B Leerzeichen und Zeilenumbriiche der Quelldatei beim Speichern ge ndert wird Das Speichern der WSDL4J Objektstruktur ist in dem Toolkit sehr einfach implementiert Die fest definierten bekannten Elemente z B lt definitions gt lt types gt lt portType gt und lt operation gt werden nach einem festen Schema formatiert Beispielsweise sind Zeilenumbriiche und Einriickungen mit zwei Leerzeichen hart codiert Nicht bekannte Elemente wie z B das lt docpart gt und lt addressee gt Element werden ohne Zeilenumbr che und extra Einr ckung im lt documentation gt Element geschrieben Daher wurde der Quellcode von WSDL4J angepasst Die lt docpart gt Elemente werden nun eine Ebene tiefer einger ckt als das lt documentation gt Element und auch die Art z B Leer oder Tabulatorzeichen und jeweilige Anzahl der Einr ckungen kann nun wenigstens ber eine globale Konstante angepasst werden Weitere Anpassungen wie z B Zeilenumbr che f r lt addressee gt Elemente stehen noch aus 2 Mangel WSDLAJ ignoriert alle XML Kommentare beim Parsen der
77. erwaltet Deswegen wird die Rolle SOURCE auch der Klasse GetFeedbackCall zugeordnet und dort beschrieben Nun braucht nur noch die Rolle PRIMARY KEY zugeordnet werden Es muss also eine Methode existieren mit der gesetzt wird f r wen das Feedback abgerufen werden soll Nach kurzem Suchen ist die Methode setUserID String userID ermittelt Wenn hier ber eine Benutzer ID gesetzt wird wird beim Aufruf von getFeedback dieses Kriterium ber cksichtigt Der Parameter userID erh lt also die Rolle PRIMARY KEY und die Methode die Rolle ACTION zusammen mit einer kurzen Beschreibung ihrer Funktion Zum Schluss kann die erfasste Dokumentation gespeichert werden wodurch sie in den Quelltext geschrieben wird Wenn ein Entwickler diese Dokumentation liest erf hrt er gen gend ber die Funktionsweise damit er das Feedback f r einen Benutzer abrufen kann In Abbildung 7 4 ist die resultierende Dokumentation gezeigt die direkt an der Methode GetFeedback erfasst wurde Wie eingangs beschrieben sind f r die Ausnahmen keine Dokumentationen erfasst worden 108 7 1 Fallbeispiel o FeedbackDetailType com ebay sdk call GetFeedbackCall getFeedback User user throws ApiException SdkException Exception Role ACTION Denier Retrieves the accumulated feedback left for a specified user or the summary PEF feedback data for a specific transaction or item Role FORMULA Scope implicit Tester Look at
78. esten und geringeren Satz an unterst tzten Programmier und Beschreibungssprachen Diese Korrelation zwischen der Anzahl an unterst tzten Sprachen und der Eigenschaft ob das Werkzeug erweiterbar konzipiert wurde sieht man gut in der Tabelle 4 4 34 4 2 Unterstiitzung der Dokumentation mit thematischen Rollen Anzahl unterstiitzter Programmier Erweiterbar fiir Sprachen mit Name und Beschreibungssprachen Kommentaren CppDoc 1 Nein Javadoc 1 Nein RDoc 1 Nein YARD 1 Nein Imagix 4D 2 Nein VSdocman 2 Nein DOC 3 Nein GenHelp 3 Nein Document X 4 Nein Help Generator 4 Nein HeaderDoc 9 Nein Doxygen 11 Nein Doc O Matic 11 Ja ROBODoc 15 Ja Natural Docs 19 Ja TwinText 25 Ja Universal Report Ja Tabelle 4 4 Korrelation zwischen Erweiterbarkeit und Anzahl unterst tzter Programmier und Beschreibungssprachen von den untersuchten Dokumentationssystemen Die in diesem Kapitel gezeigten Tabellen sind sind nur auszugsweise dargestellt Die vollst ndigen Tabellen befinden sich im Anhang A 35 4 3 Fazit 4 3 Fazit Aus den exemplarisch betrachteten Dokumentationssystemen wird erkennbar dass die existierenden Werkzeuge haupts chlich bei der Erstellung einer Dokumentation aus dokumentierten Quelltexten gute Unterst tzung leisten Sie bereiten diese Informationen gut auf und berf hren sie in eine f r Menschen gut lesbare Form HTM
79. f 16 02 2011 o V 0 J The JaxMe JavaSource framework JaxMeJS Version 0 5 2 Internet http ws apache org jaxme js Abruf 16 02 2011 o V 0 J javaparser Java 1 5 Parser and AST Version 1 0 8 Internet http code google com p javaparser Abruf 16 02 2011 o V 0 J Eclipse Java development tools JDT Core Component Version 3 6 Internet http www eclipse org jdt core Abruf 16 02 2011 143 Literaturverzeichnis Schraitle Thomas 2009 The Value of Good Documentation Internet http lizards opensuse org 2009 01 16 the value of good documentation Stand 16 01 2009 Abruf 11 01 2011 Thompson Henry S et al 2001 XML Schema Part 1 Structures Internet http www w3 org TR 2001 REC xmlschema 1 20010502 Stand 02 05 2001 Abruf 07 02 2011 144 Eidesstattliche Erklarung Eidesstattliche Erklarung Ich erkl re hiermit an Eides Statt dass ich die vorliegende Arbeit selbstst ndig und ohne Benutzung anderer als der angegebenen Hilfsmittel angefertigt habe die aus fremden Quellen direkt oder indirekt bernommenen Gedanken sind als solche kenntlich gemacht Die Arbeit wurde bisher in gleicher oder hnlicher Form keiner anderen Pr fungskommission vorgelegt und auch nicht ver ffentlicht Regesbostel 01 03 2011 Ort Datum Unterschrift Vor und Nachname 145
80. f die Schaltfl che zum Hinzuf gen einer Dokumentation geklickt wird wird ein neues Documentation Objekt erstellt dieses wird der Documentation Liste im Selection Objekt hinzugef gt und die Methode fireChangeEvent aufgerufen Das EditArtifactDocumentationComposite registriert dann die nderung und aktualisiert die Zust nde der abh ngigen Komponenten dementsprechend Es setzt jeweils ein aktualisiertes Selection Objekt ber die Methode setSelection Dadurch ver ndert sich dann der Zustand der Komponenten Die Ver nderung der Oberfl che wird also nicht direkt von einer Komponente gemacht sondern sie ndert lediglich ihr Selection Objekt und informiert dann die Elternkomponente Da nun ein Documentation Objekt in der Liste des Selection Objekts vorhanden ist wird daf r ein DocumentItemComposite und eine Entfernen Schaltfl che erzeugt und in die jeweilige Liste im DocumentItemListComposite hinzugef gt F r das DocumentItemComposite wird das entsprechende Selection Objekt erzeugt und mit den n tigen Daten initialisiert Das Selection Objekt wird dann ber die setSelection Methode der 100 6 4 User Interface UI Document Tabelle 6 11 temComposite bergeben wodurch es ihren Zustand erh lt siehe private void addNewDocumen Documentation documentation List lt Addressee gt add List lt ThematicRole gt thema resseeList DocumentItemComp
81. face zusammen mit weiteren XML Angaben besteht Ein anderes Plugin das sich zu diesem Extension Point verbinden m chte muss dieses Interface in seiner Extension implementieren Das zweite Plugin erweitert somit die Funktionalit t des ersten Plugins ohne dass das erste Plugin genaue Kenntnisse tiber das zweite hat Es wei nichts was ber die geforderten Angaben aus dem Extension Point hinausgeht 5 2 2 iDoclt Wie eingangs beschrieben soll sich iDoclt in die Entwicklungsumgebung Eclipse integrieren und deren Komponenten als Eclipse Plugins realisiert werden Zur Erweiterung des Werkzeugs um unterst tzte Programmier und Beschreibungs sprachen existieren noch weitere M glichkeiten neben dem in Kapitel 5 2 1 beschriebenen Konzept der Extension Points und Extensions Eclipse Plugins k nnen auch durch Plugin Fragments und auch herk mmliche Varianten erweitert werden Zu den herk mmlichen Varianten z hlen das Nachladen von Dateien oder Installieren von immer komplett neuen Programmversionen um eine neue Programmier oder Beschreibungssprache hinzuzuf gen e Plugin Fragment Ein Plugin Fragment hnelt physisch sehr einem normalen Plugin W hrend der Laufzeit integriert es sich aber logisch in ein anderes Plugin Host Plugin Es ist dann so als wenn nur ein Plugin existieren w rde Dadurch hat das Fragment auch uneingeschr nkten Zugriff auf die Ressourcen des Host Plugins Ein Fragment dient haupts chlich zur optionalen E
82. fh rt z B A aA gt aaA gt aaB gt aabB gt aabbB gt aabbb X Die Produktionsregeln werden so lange angewendet bis alle Nichtterminale durch Terminale ersetzt worden sind da ein Wort nur aus Terminalen bestehen darf Es wird die formale Sprache L G a b n m EN An gt 0 A m gt 1 gebildet Eine Grammatik hei t kontextfrei wenn sie ausschlie lich Produktionsregeln besitzt bei denen auf der linken Seite der Produktionsregeln genau ein Nichtterminalsymbol steht z B A gt aA mit A E N Eine Grammatik ist kontextabh ngig wenn eine Ableitung eines Nichtterminals nur in einem bestimmten Kontext m glich ist z B xAy xaAy mit AE N Das bedeutet dass die Regel nur angewendet werden darf wenn A zwischen x und y steht also in einem bestimmten Kontext 36 Vgl Socher Rolf Theoretische Grundlagen der Informatik 2008 Kontextfreie Grammatiken S 74ff 39 5 1 Grammatiken 5 1 2 Generische Grammatik f r Schnittstellen In diesem Kapitel wird eine kontextfreie Grammatik entwickelt die die Struktur der meisten Programmier und Beschreibungssprachen abbilden kann Aus den Vorgaben der AKRA GmbH siehe Kapitel 3 4 resultiert f r diese Bachelorarbeit dass Parser f r Java und WSDL entwickelt werden Daher orientiert sich die zu entwickelnde Grammatik haupts chlich an diesen Sprachen F r Java wurde die Sprachspezifikation in der aktuellen dritten Edition herangezogen und f r WSDL die Version
83. gebaut siehe Abbildung 6 3 Damit die Dokumentationen sp ter wieder an die richtigen Stellen in der WSDLAJ Objektstruktur geschrieben werden erhalten alle Klassen au er die Klasse WSDLParameter eine Referenz zu dem korrespondierenden Objekt 54 Legende Optional 0 bis 1 Mal vorhanden Mehrfach vorhanden 0 bis beliebig oft 55 Vgl Anhang B 82 6 2 Parser fiir WSDL Die Klasse ws lt lt Java Class gt gt WSDLInterfaceArtifact de akra idocit wsdl structure o wsdlDefinition Definition Java Class gt gt GS InterfaceArtifac de akra idocit structure interfaces 0 lt lt Java Class gt gt WSDLInterface de akra idocit wsdl structure o portType PortType lt lt Java Class gt gt WSDL Operation de akra idocit wsdl structure a operation Operation sadaya Class gt gt 5 Interface de akra idocit structure Jo operations 0 innerinterfaces lt lt Java Class gt gt lt lt Java Class gt gt WSDLMessage de akra idocit wedl structure o messageRef YVSDLElemert parameters 0 lt lt Java Class gt gt WSDLParameter de akra idocit wsdl structure lt lt Java Class gt gt Parameter de akra idocit structure complexT ype 0 Abbildung 6 3 Klassen der allgemeinen Schnittstellenstruktur f r WSDL Dokumentation zu denen der WSDLMessage geschrieben
84. gebnisse einer Produktion mit eckigen Klammern eingeschlossene Symbole sind optional ein oder keinmal vorhanden und mit geschweiften Klammern eingeschlossene Symbole k nnen null bis beliebig oft wiederholt werden InterfaceDeclaration NormallnterfaceDeclaration NormallnterfaceDeclaration InterfaceModifier interface Identifier ExtendsInterfaces InterfaceBody InterfaceBody InterfaceMemberDeclaration InterfaceMemberDeclaration InterfaceDeclaration AbstractMethodDeclaration ClassDeclaration ClassOrInterfaceType ClassType InterfaceType AbstractMethodDeclaration AbstractMethodModifier ResultType MethodDeclarator Throws ClassDeclaration NormalClassDeclaration EnumDeclaration NormalClassDeclaration ClassModifier class Identifier Super Interfaces ClassBody ClassBody ClassBodyDeclaration ClassBodyDeclaration ClassMemberDeclaration ConstructorDeclaration ClassMemberDeclaration MethodDeclaration FieldDeclaration ClassDeclaration InterfaceDeclaration ro teens r Tabelle 6 8 Auszug der Java Sprachspezifikation f r eine Interface Deklaration in EBNF Wie dem Auszug der Interface Deklaration entnommen werden kann k nnen Schnittstellen NormalInterfaceDeclaration auch die vom Aufbau her sehr hnlichen Klassen NormalClassDeclaration und Enumerationen Enum
85. he Abbildung 7 1 soweit dokumentiert werden dass ein Entwickler erf hrt wie das Feedback f r einen bestimmten Benutzer abgerufen wird M gliche auftretende Ausnahmen sollen hier zur Vereinfachung nicht ber cksichtigt werden Dazu soll einmal das Javadoc mit iDoclt und einmal mit den Hilfsmitteln von Eclipse Raster von den sichtbaren Schnittstellenelementen erstellt werden Das Hauptaugenmerk liegt beim Dokumentieren auch darauf wie gut ein Autor beim Dokumentieren unterst tzt wird Als Basis f r die einzelnen Beschreibungen soll das original Javadoc der eBay SDK for Java API dienen 71 Vel 0 V eBay SDK for Java o J 72 Vel 0 V eBay SDK for Java Library Reference Documentation 0 J getFeedbackCall 103 7 1 Fallbeispiel C com ebay sdk call GetFeedbackCall userID String itemID String returnedFeedbackDetails FeedbackDetailType feedbackSummary FeedbackSummaryType feedbackScore int GetFeedbackCall apiContext ApiContext void getFeedback FeedbackDetailType getUserID String setUserID userID String void getltemID String setItemID itemID String void getFeedbackScore int getFeedbackSummary FeedbackSummaryType getReturnedFeedbackDetails FeedbackDetailType Abbildung 7 1 Auszug der Klasse GetFeedbackCall 7 1 1 Dokumentation mit iDoclt Bevor mit dem Dokumentieren angefangen werden kann m ssen f r iDoclt die thematischen Raster f r die verwendeten
86. hompson Henry S et al XML Schema Part 1 2001 Complex Type Definitions und Simple Type Definitions 41 5 1 Grammatiken Operation Input Message Output Message Fault Message Element 1 Element 2 Element 3 Abbildung 5 2 Beispielhafter Aufbau eines lt portType gt Elements der WSDL 1 1 Spezifikation Fiir Java wiirde es reichen wenn fiir die Eingaben und Ausnahmen Mengen von Parametern und f r den Ergebnistypen ein einzelner Parameter verwendet werden wirde WSDL ben tigt an dieser Stelle aber mehr Eine Operation in WSDL verwendet f r die Ein lt input gt und Ausgaben lt output gt jeweils ein lt message gt Element und f r Fehler lt fault gt eine Menge von lt message gt Elementen Jedes lt message gt Element besteht jeweils wiederum aus einer Menge von lt part gt Elementen Weiterhin besitzt ein lt message gt Element selbst Eigenschaften weswegen es sich nicht als Menge von Parametern lt part gt Elemente darstellen l sst Es muss ein Element in der allgemeinen Struktur definiert werden das ein lt message gt Element abbildet Dieses Element soll Parameters hei en da es eine Menge von Parametern zusammenfasst F r eine Methode in Java wird ein Parameters Element die Menge der Eingabeparameter enthalten und ein weiteres Parameters Element eine einelementige Menge f r den Ergebnistypen Da WSDL eine Menge der Parameters Elemente
87. hst Kategorien abgeleitet in die die Systeme gruppiert werden k nnen Daraufhin werden die Systeme berpr ft inwieweit sie den in Kapitel 3 aufgestellten Anforderungen gen gen und zum Schluss werden die Ergebnisse der Evaluierung zusammengefasst 4 1 Kategorien von Dokumentationssystemen Dokumentationssysteme Werkzeug Format 4 Quelltext Aufbereiter Quelltext Aufbereiter ohne semantische Annotation 1 mit unstrukturierter mit strukturierter semantischer semantischer Annotation 2 Annotation 3 Abbildung 4 1 Kategorien von Dokumentationssystemen Bei der Untersuchung der Dokumentationssysteme hat sich herausgestellt dass diese viele hnliche Eigenschaften und Funktionen haben Von den Gemeinsamkeiten ausgehend konnten Kategorien abgeleitet werden in denen die Dokumentations systeme eingeteilt werden k nnen siehe Abbildung 4 1 29 4 1 Kategorien von Dokumentationssystemen Kategorie 1 Quelltext Aufbereiter ohne semantische Annotation In der Kategorie 1 befinden sich Werkzeuge die sich nur auf den Quelltext konzentrieren und diesen analysieren wie z B Help Generator und Universal Report Sie bereiten den Quelltext auf indem z B die Eingaben Ausgaben und Fehler einer Operation gegliedert dargestellt werden oder alle Stellen referenziert werden von wo aus eine Operation aufgerufen wird Hierbei werden keine Informationen aus Kommentaren oder anderen Quellen ber cksichtigt D
88. iType com ebay soap eBLBaseComponents FeedbackDetailType Role OBJECT Developer The FeedbackDetailType object Throws SdkException Element com ebay sdk SdkException com ebay sdk SdkException Developer Is thrown if the user is undefined Abbildung 6 5 Javadoc Beispiel in HTML mit iDoclt Dokumentationsbl cken 6 3 3 Implementierungsdetails des Java Parsers Die Parser Erweiterung fiir Java soll die Sprachspezifikation in der aktuellen dritten Edition unterst tzen Bei der Entwicklung der allgemeinen Schnittstellenstruktur in Kapitel 5 1 2 wurden bereits die wichtigsten Schnittstellenelemente auf abstraktem Niveau vorgestellt In Tabelle 6 8 ist die Spezifikation einer Interface Deklaration noch einmal auszugsweise in der EBNF aufgef hrt damit der Aufbau und die Zuordnung zu den Klassen der allgemeinen Schnittstellenstruktur gezeigt werden kann Es sind nicht alle Elemente der Spezifikation in dem Auszug enthalten und die Produktionen werden teils nicht vollst ndig bis zum Terminalsymbol aufgef hrt Die gro geschriebenen W rter z B InterfaceDeclaration und Identifier 63 Siehe Gosling James et al Java Language Specification 2005 91 6 3 Parser fiir Java stellen Nichtterminalsymbole und die klein geschriebenen Worter z B class und interface sowie die Zeichen in einfachen Hochkommata z B und stellen Terminalsymbole dar Ein vertikaler Strich trennt alternative Er
89. ibungen estellt werden 136 D 3 Bedienungsanleitung Select Signature Element Document Signature Element getFeedback Method S O cetreedbackCall Class AAA AAA H GetFeedbackCall Constructor Thematic Role ACTION v Scope EXPLICIT v ir a al Analyst Builder Integrater Tester Developer lt gt e ReturnType T 8 5 throws 3 Retrieves the accumulated feedback left For a specified user or the summary feedback data for a specific transaction or item ApiException Type ApiException SdkException Type SdkException Exception Type Exception EH O getUserID Method 0 setUserID Method a E E Parameters _ _ II gt userID Type String a getItemID Method 3 Thematic Role FORMULA v Scope IMPLICIT vw lt u Analyst Builder Integrater Tester Developer au Overview of recommended roles for getFeedback Method Lock at http pages ebay com help feedback howitworks html Calculating Operations A ACTION Associated AGENT Associated 7 FORMULA Associated OBJECT Associated SOURCE v Abbildung D 6 iDoclt Editor mit der ge ffneten Klasse GetFeedbackCall aus dem eBay SDK for Java Wenn ein Element einer Operation d h die Operation selbst oder ein im Navigationsbaum hierarchisch darunter liegendes Element selektiert wird werden unten links im Fenster die thematischen Raster und Rollen zu dem Verb im Operationsbeze
90. ichern der nderungen in die Quelldatei Q DocumentationEditor Parserlmpl tzer Actor l saveChanges 1 1 doS LoS yt a writelnterface IntArtifact IFile K 1 1 1 1 getExtensionRegistry Registered Extensions Benu 1 1 1 2 write IntArtifact IFile file is supported i BRENNER N ais en Abbildung 5 20 Ablauf der Methodenaufrufe beim Speichern von Anderungen Eclipse ruft zum Speichern der Anderungen im DocumentationEditor die Methode doSave auf Dort wird die Methode writeInterfaceArtifact des PersistenceService s aufgerufen und die im DocumentationEditor gespeicherte Dateiressource Datentyp IFile und das ge nderte InterfaceArtifact mitgegeben Der PersistenceService ruft dann von Eclipse wieder alle registrierten Parser Extensions ab und wenn ein passender Parser dabei ist wird dem das InterfaceArtifact und IFile bergeben damit dieser es in die Dateiressource speichern kann 69 6 Implementierung 6 Implementierung Dieses Kapitel beschreibt die Realisierung der einzelnen Komponenten von iDoclt Zuerst wird die Plattform Core mit der abstrakten allgemeinen Schnittstellenstruktur beschrieben Danach wird die Implementierung der Parser Erweiterungen f r WSDL und Java erl utert und abschlie end die der grafischen Oberfl che 6 1 Plattform Core Die Plat
91. ichner angezeigt Ist ein anderes Element selektiert oder enth lt die Operation kein Verb bzw kein bekanntes englisches Verb bleibt das Kontrollelement leer Werden die thematischen Raster angezeigt werden auch die bereits zugeordneten thematischen Rollen als Associated gekennzeichnet Die vergebenen Rollen werden in den Dokumentationen von allen Elementen einer Operation sowie in den Dokumentationen der Elemente die auf dem direkten Weg von der Operation bis hoch zum Wurzelelement dem Artifact bzw der Datei liegen In dem Beispiel aus Abbildung D 6 werden die Dokumentationen aus den Elementen der Methode getFeedback Method und auch die Dokumentationen von den Elementen GetFeedbackCall Class und GetFeedbackCall java Artifact nach bereits zugeordneten Rollen berpr ft 137 D 3 Bedienungsanleitung Die Anderungen an den Dokumentationen werden mit der Speichern Schalftfache von Eclipse oder mit der Tastenkombination Strg S gespeichert Falls Anderungen in der Zwischenzeit an der Quelldatei get tigt wurden werden sie mit dem Speichern ohne einen Hinweis tiberschrieben 138 E Abkiirzungsverzeichnis E Abk rzungsverzeichnis API APSL ASB AST DITA DOM EBNF GNU GNU FDL GNU GPL GPL GUI HTML ID MIT 0 J 0 0 0 V O Doku PDF POC UI Application Programming Interface Apple Public Source License Abstrakter Syntaxbaum Abstract Syntax Tree
92. ichner mit einem Verb beginnt Die Operation in Tabelle 2 1 ist ein Beispiel dafiir Die aus der Konvention resultierenden Bezeichner haben den Charakter eines Imperativsatzes Satz in Befehlsform Unter Einbeziehung des gegebenen Eingabeparameter UserID zum Beispiel get the feedback by UserID 15 Vgl Gruber J S Lexical Relations 1965 16 Vel Fillmore C J Case for Case 1968 S 1 90 17 Vel 0 V eBay Trading API o J GetFeedback 18 Vgl Martin Robert C Clean Code 2009 Verbs and Keywords S 43 19 Vel Krause Jan Christian Thematic Grids 2010 14 2 Dokumentation von Operationen mit thematischen Rastern Der Formalismus um die Argumente eines Verbs zu bestimmen hei t thematisches Raster Thematic Grid Die ben tigten Argumente hei en thematische Rollen Thematic Role Ein vereinfachtes thematisches Raster f r das Verb get im Kontext der Operation Get Feedback ist in Tabelle 2 2 abgebildet Thematisches Raster f r to get AGENT obligatorisch Ausf hrende Instanz ACTION obligatorisch Eine bestimmte Information abrufen OBJECT obligatorisch Die gesuchte Information CRITERION oder Eindeutiges Kriterium welches angibt ob das PRIMARY KEY optional aktuell gepr fte OBJECT das gesuchte ist SOURCE optional Quelle bzw Speicher aus dem die durchsuchten OBJECTS stammen FORMULA optional Formel zur Berechnung der Information
93. ichtlich dargestellt werden k nnen z B in der resultierenden API Dokumentation im HTML Format und sie einfach mit einem XML Parser wieder eingelesen werden k nnen 61 Vgl Martin Robert C Clean Code 2009 S 69 89 6 3 Parser fiir Java Ein Dokumentationsblock soll in einer HTML Tabelle mit zwei Spalten dargestellt werden In der ersten Spalte stehen die Attributnamen und in der zweiten Spalte die dazugeh rige Beschreibung Die Reihenfolge der Attribute ist Element Role Scope Namen von Adressaten Das Attribut Element wird nur bei Parametern Ergebnistyp und Ausnahmen einer Methode verwendet Wenn keine thematische Rolle f r ein Element vergeben ist wird das Attribut Role auch nicht angezeigt Wenn eine vergeben wurde wird die thematische Rolle in der zweiten Spalte eingef gt Bei dem Attribut Scope bedeutet ein nicht Vorhandensein dass es EXLPICIT ist ansonsten ist es mit dem Wert IMPLICIT vorhanden Diese Konvention wurde gew hlt um die Dokumentation nicht unn tig zu verl ngern Nach den fest vergebenen Attributen folgen die variablen Namen von Adressaten Hierbei wird der Text in der ersten Spalte als Name f r einen Adressaten verwendet und der Text in der zweiten Spalte als Freitextbeschreibung f r diesen Adressaten Abbildung 6 5 zeigt diese Struktur anhand einer beispielhaften Javadoc Dokumentation im HTML Format Dazu wurde die Methode Get Feedback aus der Klasse GetFeedbackCall des eBay
94. ie Dokumentation ist hier das Ergebnis dieser Aufbereitung das in ein anderes Format meist HTML gespeichert wird Kategorie 2 Quelltext Aufbereiter mit unstrukturierter semantischer Annotation Die Werkzeuge der Kategorie 2 z B RDoc bereiten den Quelltext auch auf nehmen aber noch unstrukturierte Informationen aus Quelltextkommentaren auf Mit unstrukturierten Informationen ist einfacher Freitext als Beschreibung gemeint z B einer Operation Kategorie 3 Quelltext Aufbereiter mit strukturierter semantischer Annotation In der Kategorie 3 wird ein durch Schl sselw rter strukturierter Text der in Quelltextkommentaren gespeichert ist mit in die Dokumentation aufgenommen Die Werkzeuge aus dieser Kategorie unterst tzen meistens ein eigenes Format und teilweise auch mehrere verschiedene Formate Hierbei handelt es sich um Formate die Schl sselw rter wie bei Javadoc z B param return see oder 6 nat rlich sprachliche wie bei Natural Docs z B Parameters Returns oder See Also verwenden aber auch Formate die XML Elemente in die Kommentare integrieren um die Beschreibungen zu strukturieren Bei den Kategorien 1 bis 3 steht mehr das Werkzeug im Vordergrund das den Quelltext ggf zusammen mit den Inhalten aus Kommentaren aufbereitet und in ein anderes Format haupts chlich HTML exportieren kann Die Dokumentationen werden i d R in Kommentaren direkt im Quelltext gespeichert
95. iese ableitbar sind Wie in Tabelle 4 3 zu erkennen ist unterst tzt keines der untersuchten Dokumentationssysteme den Autor durch eine semantische Analyse um diese nicht sichtbaren aber beschreibungsw rdigen Elemente herauszufinden Einige bieten die Erstellung eines textuellen Rasters von den sichtbaren Elementen einer Operation im Quelltext an und einige andere wie z B VSdocman und Doc O Matic ber eine grafische Oberfl che Die Formate aus der Kategorie 4 offerieren nichts dergleichen 33 4 2 Unterstiitzung der Dokumentation mit thematischen Rollen Sie haben lediglich eine eigene Gliederungsvorschrift nach der Dokumentationen strukturiert werden k nnen Nicht sichtbare Elemente Name abbildbar ableitbar CppDoc o Doc O Matic o DOC E Document X o E Doxygen o x GenHelp o 7 HeaderDoc 2 Javadoc o 2 Natural Docs o ROBODoc 2 TwinText z VSdocman o YARD o DITA o DocBook o Tabelle 4 3 Unterst tzung nicht sichtbarer Elemente von den untersuchten Kategorie 3 und 4 Dokumentationssystemen Die Werkzeuge wurden auch auf die Erweiterbarkeit von unterst tzten Programmier und Beschreibungssprachen gepr ft Die Formate Kategorie 4 sind hierbei au en vor da sie unabh ngig von einer Programmiersprache eingesetzt werden Nur f nf der 17 untersuchten Werkzeuge sind erweiterbar um Sprachen die Kommentare erlauben Die anderen haben ihren f
96. iir das Verb to get im Kontext der Operation GetFeedback aus der eBay Trading AP 15 Tabelle 2 3 Auszug aus der Schnittstellenbeschreibung der Operation GetFeedback aus der eBay Trading API mit beispielhafter Zuordnung von thematischen Rollen eu Na EEE Een 17 Tabelle 3 1 Auswahl an m glichen Adressaten ooooonnocnnoccnonncionoconnonoconnonoccnanancnnnnos 23 Tabelle 3 2 Enumerationswerte von DetailLevelCodeType aus der eBay Trading API ne leere 26 Tabelle 3 3 Auszug aus der Schnittstellenbeschreibung der Operation GetFeedback aus der eBay Trading APPLE 26 Tabelle 4 1 Unterst tzte Dokumentationstypisierungen von den untersuchten Kategorie 3 und 4 Dokumentationssystemen ucesseseeensenneennnn 32 Tabelle 4 2 Fortsetzung Unterst tzte Dokumentationstypisierungen von den untersuchten Kategorie 3 und 4 Dokumentationssystemen 33 Tabelle 4 3 Unterst tzung nicht sichtbarer Elemente von den untersuchten Kategorie 3 und 4 Dokumentationssystemen uessnnsensesssnesennnnnsnnnennsnnnnnnnnen 34 Tabelle 4 4 Korrelation zwischen Erweiterbarkeit und Anzahl unterst tzter Programmier und Beschreibungssprachen von den untersuchten Dokumentationssystemen od nes 35 Tabelle 5 1 Beispiel einer Grammatik ont an 39 Tabelle 5 2 Auszug der WSDL 1 1 Spezifikation f r das lt portType gt Element 41 Tabelle 5 3 Allgemeine Grammatik einer Schnittstellenstruktur in EBNF vereinfachte Darstoll
97. ilden soll Danach werden die Komponenten von iDoclt 37 5 Systementwurf und deren Modularisierung als Eclipse Plugins vorgestellt Die Parser Erweiterungen und die grafische Oberfl che werden danach detaillierter erl utert Abschlie end wird beschrieben wie die einzelnen Komponenten ber die bereitgestellten Services miteinander agieren 5 1 Grammatiken In diesem Kapitel wird die erw hnte generische Grammatik zur Abbildung der meisten Programmier und Beschreibungssprachen entwickelt Das Konzept der formalen Grammatiken wird in einem hohen Abstraktionsniveau verwendet dazu wird zuerst eine kurze Einf hrung in die formalen Grammatiken gegeben 5 1 1 Grundlagen formaler Grammatiken In der theoretischen Informatik ist eine Grammatik G ein Regelwerk wie syntaktisch korrekte W rter einer formalen Sprache L gebildet werden Sie ist als ein Viertupel G N P S definiert Das Vokabular einer Grammatik besteht aus einer endlichen Menge von Variablen sogenannten Nichtterminalsymbolen oder Nichtterminale N und einer endlichen Menge von Zeichen Terminalsymbole oder Terminale die das Alphabet 2 bilden Terminale k nnen z B Ziffern Buchstaben und Sonderzeichen sein Die Nichtterminalsymbole sind nur in Zwischenschritten einer Ableitung enthalten und d rfen nicht im endg ltigen Wort vorkommen Ausgehend von einem Startsymbol S e N lassen sich durch Produktionsregeln aus einer Menge von Regeln P W rter ableiten Ein Wor
98. im Quelltext Nein Ja Nein DITA Open Source 4 externe Datei Ja Nein Nein DocBook GNU FDL 4 externe Datei Ja Nein Nein Tabelle A 1 Kategorien und allgemeine Informationen zu den untersuchten Dokumentationssystemen A Auswahl existierender Dokumentationssysteme Unterstiitzte Dokumentationstypisierungen Seit welcher Version Name Eingabe Ausgabe Fehler Autor Version enthalten Veraltet Help Generator 2 z 3 Imagix 4D f a o Universal Report 2 Z RDoc a z E CppDoc Doc O Matic DOC Document X 4 o o o 0 Doxygen 4 GenHelp de HeaderDoc de 3 Javadoc en 4 Natural Docs de o ROBODoc as o o 0 TwinText _ 4 VSdocman 5 YARD E DITA o o o o o 0 o DocBook o o o o o o o Tabelle A 2 Unterst tzte Dokumentationstypisierungen von den untersuchten Dokumentationssystemen Legende te ist vorgesehen nicht m glich o nicht vorgesehen aber m glich 121 A Auswahl existierender Dokumentationssysteme Unterstiitzte Dokumentationstypisierungen Untypisierter Zielgruppen Bereich gerichtete Erweiterbar Name Referenz Beschreibung Freitext Beschreibung um Typen Help
99. imiters O JavaParser void O WSDLParser void O parse iFile IFile InterfaceArtifact O parseliFile IFile InterfaceArtifact O writefinterfaceStruckure InterfaceArtifact iFile IFile void O isSupported type String boolean O getSupportedType String O getDelimiters Delimiters O writefinterfaceStruckure InterfaceArtifact iFile IFile void O isSupported type String boolean e getSupportedType String O getDelimiters Delimiters Abbildung 5 12 Klassendiagramm des Interfaces Parser mit seinen Kindklassen lt xml version 1 0 encoding UTF 8 gt lt eclipse version 3 4 gt lt plugin gt lt extension point de akra idocit lt client class de akra idocit lt extension gt lt plugin gt extensions Parser gt wsdl services WSDLParser gt cy Mm Tabelle 5 4 Inhalt der plugin xml f r die WSDL Parser Erweiterung Die abstrakte allgemeine Schnittstellenstruktur die von der Core Komponente zur Verf gung gestellt wird muss beerbt und bei Bedarf um weitere Attribute erg nzt werden Die zus tzlichen Attribute sollen alle Informationen enthalten die f r die R ckf hrung und f r das Speichern der Struktur notwendig sind Diese f r eine spezielle Programmier oder Beschreibungssprache erweiterte Schnittstellenstruktur ist durch die Komponente Extended Interface Artifact Structure dargestellt Im Implementierungskapitel wird die erweitert
100. in der grafischen Oberfl che sollen nicht nur Freitextfelder verwendet werden Abh ngig von der zugeordneten thematischen Rolle soll ein entsprechender Editor erscheinen Beispielsweise k nnte zu der Rolle FORMULA ein Formeleditor zur Eingabe einer Formel angezeigt werden Weiterhin k nnte analysiert werden wie Entwickler und Autoren arbeiten und danach k nnte das Benutzungsmodell weiter angepasst werden 119 A Auswahl existierender Dokumentationssysteme Format Speicherort Unterstiitzt Software der Schl ssel Javadoc Name Lizenz Kategorie Dokumentation XML w rter Format Help Generator Proprietar 1 externe Datei Nein Nein Nein Imagix 4D Propriet r 1 externe Datei Nein Nein Nein Universal Report Propriet r 1 externe Datei Nein Nein Nein RDoc Ruby License 2 im Quelltext Nein Ja Nein CppDoc Open Source 3 im Quelltext Nein Ja Ja Doc O Matic Propriet r 3 im Quelltext Ja Ja Ja DOC GPL 3 im Quelltext Nein Ja Nein Document X Propriet r 3 im Quelltext Ja Nein Nein Doxygen GPL 3 im Quelltext Ja Ja Ja GenHelp Propriet r 3 im Quelltext Nein Ja Ja HeaderDoc APSL 3 im Quelltext Nein Ja Nein Javadoc GPL 3 im Quelltext Nein Ja Ja Natural Docs GPL 3 im Quelltext Nein Ja Ja ROBODoc GPL 3 im Quelltext Nein Ja Nein TwinText Propriet r 3 im Quelltext Nein Ja Nein VSdocman Propriet r 3 im Quelltext Ja Nein Nein YARD MIT License 3
101. ist dieses exemplarisch gezeigt Preferences iDocIt General Help E Please specify where WordNet is installed on your computer E iDoctt If you do not have Wordnet download it here amp Install Update Java WordNet Path C WordNet 3 0 dict PoS Tagger Model C postagger 2010 05 26 models left3words distsim wsj O 18 tagger Restore Defaults App E Abbildung D 1 iDoclt Preference Page In der Preference Page f r die Adressaten siehe Abbildung D 2 k nnen die verwendeten Adressaten verwaltet werden F r einen Adressaten kann ein Name und eine Beschreibung erfasst werden Preferences Addressees General A Help a Defined Address Edit selected Addressee iDoclt Defined Items Name Builder Addressees Architect enger m 7 Thematic Grids System_Builder Builder of an element who needs the most comprehensive documentation of an interface D E Thematic Roles Manager Install Update BR Java Integrater Description JavaScript Tester Developer Add Item Remove selected Item s Restore Defaults Apply Abbildung D 2 iDoclt Preference Page f r Adressaten 133 D 3 Bedienungsanleitung In der Preference Page fiir thematische Raster siehe Abbildung D 3 werden die thematischen Raster verwaltet Hier k nnen neue Raster erstellt oder vorhandene gel scht werden Zu einem thematischen Raster kann ein Name erfasst werden sowi
102. it integriert wie z B bei Javadoc k nnen weiterhin deren M glichkeiten zur Dokumentation verwendet werden Die weiteren Metadaten k nnten daher ber das Freitextfeld im iDoclt UI mit erfasst werden Die Anforderung aus Kapitel 3 2 dass ein Dokumentationsformat thematische Rollen und adressatenspezifische Dokumentationen abbilden k nnen muss ist mit iDoclt auch umgesetzt F r jede unterst tzte Programmier oder Beschreibungssprache WSDL und Java wurde ein Format entsprechend den M glichkeiten der Sprache entwickelt dass die Anforderung erf llt Auch an das Dokumentationswerkzeug wurden einige Anforderungen gestellt siehe Kapitel 3 3 Es sollte e eine grafische Oberfl che besitzen e thematische Raster aus einem Operationsbezeichner ableiten k nnen e die thematischen Raster anzeigen k nnen e fir alle Schnittstellenelemente und den Attributen von Parametern einer Operation Dokumentationen erfassen k nnen Dokumentationen f r nicht sichtbare Elemente erfassen k nnen e adressatenspezifische Dokumentation unterst tzen e die Erfassung von thematischen Rollen und Sichtbarkeitsbereichen erm glichen e sich in eine bestehende Entwicklungsumgebung integrieren e die Dokumentation in den Quelltext schreiben und es sollte e erweiterbar um weitere unterst tzte Programmier und Beschreibungs sprachen sein Wie unter anderem in dem Fallbeispiel gesehen werden kann erf llt iDoclt diese Anforderungen Abbil
103. ittlung von zugeordneten thematischen Rollen Die Zust nde der beschriebenen Komponenten werden in der Komponente EditArtifactDocumentationComposite verwaltet das sich direkt in dem DocumentationEditor einbettet siehe Abbildung 5 16 Die Details zu den Klassen und Zust nden werden in Kapitel 6 4 beschrieben lt Java Class gt gt DocumentationEditor de akra idocit ui components lt lt Jawa Class gt EditArtifactDocumentationComposite de akra idocit ui composites lt lt Java Class gt gt lt Jawa Class gt gt DocumentitemListComposite DisplayRecommendedRolesComposite de akra idocit ui composites de akra idocit ui composites lt lt Jawva Class gt gt SelectSignatureElementComposite de akra idocit ui composites lt lt Java Class gt gt DocumentitemComposite de akra idocit ui composites Abbildung 5 16 Klassendiagramm der UI Komponenten 65 5 5 Kommunikation der Plattform Services 5 5 Kommunikation der Plattform Services In diesem Kapitel wird das Zusammenspiel von Eclipse und den Komponenten Plugins von iDoclt anhand von einigen Anwendungsf llen beschrieben Benutzer fe Registriere Ul als Editor Extension Point registrieren Als Extension an Initialisieren iDoclt Core Extension Point anmelden iDoclt Parser Abbildung 5 17 Aktivit ten beim Start von Eclipse Damit ein Benutzer iDoc
104. ksamkeit lenken muss Er wird dadurch besser unterst tzt dokumentationsw rdige Elemente zu identifizieren Somit wird potentielle Stille in der Dokumentation vermieden 113 7 4 Fazit Im Gegensatz dazu ist der Autor bei dem Raster von Javadoc auf sich alleine gestellt Er muss die Schnittstelle durcharbeiten und nicht sichtbare Elemente selbst identifizieren die dokumentiert werden sollten Dadurch dass iDoclIt nicht die sichtbaren Schnittstellenelemente als Basis f r seine Vorgaben nimmt ist die Qualit t der thematischen Raster unabh ngig von der Implementierungsweise eines Entwicklers Wie es z B bei der Methode GetFeedback aus dem Fallbeispiel der Fall ist werden die Einstellungen tiber andere Methoden get tigt und im Objekt gespeichert Die Methode erh lt keine direkten Eingaben Im Gegensatz dazu k nnten die gesamten Einstellungen als Parameter in die Methode hineingehen Dann wiirde Javadoc auch ein besseres Raster vorgeben Au erdem geht die Qualit t der thematischen Raster ber die eines Rasters von Javadoc hinaus Weil das Verb einem bestimmten Kontext zugeordnet wird sind bereits Gedanken in seine Interpretation geflossen es werden nicht nur die Rohdaten also z B die einzelnen Namen der Elemente einer Methodensignatur verwendet Bei einem thematischen Raster hat der Autor also bereits Informationen ber eine Methode erhalten und muss nicht nur mit den einfachen Daten arbeiten Damit die thematis
105. ktionen und Eigenschaften anhand eines umfassenden Kriterienkatalogs berpr ft Es wurde festgestellt dass die meisten Systeme die allgemeinen Kriterien erf llen aber nicht die speziellen Kriterien zur Dokumentation thematischer Rollen und adressatenspezifischen Beschreibungen Da kein Dokumentationssystem alle Anforderungen erf llt wurde das Werkzeug iDoclt als Eclipse Plugin entwickelt F r den Prototypen wurden Parser Erweiterungen f r Java und WSDL entwickelt sodass diese dokumentiert werden k nnen In einem Fallbeispiel hat iDoclt dann seine Vorz ge gezeigt Ein Autor erh lt durch die thematischen Raster in iDoclt einen guten Leitfaden als Unterst tzung beim Dokumentieren Dadurch und auch weil teilweise zur Dokumentation nur thematische Rollen zugeordnet werden brauchen kann eine Schnittstelle schneller dokumentiert werden Weiterhin werden potentielle Stille und auch Rauschen durch die Vorgaben der Raster bestm glich vermieden 116 8 1 Zusammenfassung und Ausblick Die thematischen Raster sind auch gleichzeitig eine Vollstandigkeitsanzeige fiir eine O Doku Bereits zugeordnete Rollen werden in iDoclt gekennzeichnet sodass der Autor immer einen berblick ber die dokumentierten Elemente hat Auch kann eine Dokumentation durch die Verwendung von thematischen Rollen potentiell gek rzt werden Eine Rolle kann u U das aussagen was sonst in einigen S tzen beschrieben werden w rde Durch die k rze
106. lemente deren lt part gt Elemente und ggf f r deren weiteren Elemente Die Dokumentation dieser Elemente wird in das lt documentation gt Element des jeweils dazugeh rigen lt input gt lt output gt oder lt fault gt Elements geschrieben Die Pfadangabe f r das Attribut signatureElement f ngt dabei mit dem Namen der lt message gt an Als Trennzeichen f r den Attributpfad sollen ein Semikolon als Elementtrenner ein Plus als Trennzeichen zwischen dem Datentyp und dem voll qualifizierten Bezeichner und ein Nummernzeichen als Trennzeichen zwischen dem Bezeichner und der Namensraumbezeichnung verwendet werden In dem Auszug aus der WSDL Spezifikation in Tabelle 6 6 ist zu sehen dass Elementnamen den Wertebereich eines NMTOKEN s aus der XML Schema Spezifikation haben Dieser Wertebereich schlie t die gew hlten Zeichen nicht mit ein weswegen sie konfliktfrei eingesetzt werden k nnen 56 Vgl Biron Paul V Malhotra Ashok XML Schema Part 2 2001 NMTOKEN 57 Vgl Bray Tim et al XML 1 0 2000 Nmtoken 84 6 2 Parser fiir WSDL Beispiel Select Signature Element e ebayAPl wsdl Artifact E ebayAPlinterface PortType 1 a GetFeedback Operation 2 GetFeedbackRequest InputMessage 3 GetFeedbackRequest Type GetFeedbackRequest Part GetFeedbackResponse OutputMessage 5 4 GetFeedbackResponse Type GetFeedbackResponse Part GetFeedbackRequest
107. ll Constructor E O getFeedback Method it getUserID Method A it setUserID Method H getItemID Method lt E E gt v Overview of recommended roles for getFeedback Method Calculating Operations SOURCE ACTION FORMULA OBJECT AGENT 4 Getter 4 Searching Operations lt ili gt Abbildung 7 2 Screenshot der Klassenstruktur von GetFeedbackCall in iDoclt Die Vorbereitungen sind nun abgeschlossen und es kann begonnen werden die Klasse in iDoclt zu dokumentieren ber das Kontextmen der Datei wird iDoclt f r die Klasse GetFeedbackCall gestartet siehe Abbildung 7 2 Das Werkzeug muss immer in einem separaten Editor ge ffnet werden nderungen in der Quelldatei werden dann nicht mehr ber cksichtigt Man muss also immer den Ablauf verfolgen dass implementiert wird dann iDoclt ge ffnet wird Dokumentation erfasst und gespeichert wird und dann iDoclt wieder geschlossen wird Danach kann weiter 105 7 1 Fallbeispiel implementiert werden Dieser Vorgang ist fiir eine schnelle Dokumentation wie sie direkt mit Javadoc m glich ist siehe Kapitel 7 1 2 umst ndlich Mit der Methode getFeedback wird der API Aufruf zum eBay Webservice get tigt und das Feedback abgerufen In dem ge ffneten iDoclt Editor werden die empfohlenen thematischen Rollen f r die Methode angezeigt wenn sie selektiert wird Da das Verb ger drei thematischen Rastern zugeordnet ist
108. lt nutzen kann muss er zuerst Eclipse starten siehe Abbildung 5 17 Beim Start l dt Eclipse u a die hinterlegten Plugins Diese initialisieren sich und registrieren sich bei Eclipse je nach ihren Einstellungen bzw ihrem Zweck Die UI Komponente registriert sich bei Eclipse als Editor damit sie ber das Kontextmen einer Datei ge ffnet werden kann Die Core Komponente 66 5 5 Kommunikation der Plattform Services registriert den Extension Point damit sich Parser Erweiterungen an diesen anmelden k nnen Die Parser Erweiterungen melden sich dann bei diesem Extension Point als Extension an Wenn alle Komponenten von Eclipse geladen sind wird die Oberfl che ge ffnet und der Benutzer kann anfangen zu arbeiten DocumentationEditor Parserlmpl Benutzer Actor 1 openFile 1 1 init 1 1 1 loadinterface IFile 1 1 1 1 getExtensionRegistry Registered Extensions z gt 1 1 1 2 parse lFile file is supported InterfaceArtifact Interface Artifact 1 1 2 setSelection initialize the D iDoclt UI II Abbildung 5 18 Ablauf der Methodenaufrufe beim ffnen einer Datei in iDoclt Wenn der Benutzer eine Datei ber dessen Kontextmen mit iDoclt ffnet wird der DocumentationEditor siehe Abbildung 5 16 von iDoclt initialisiert Das Sequenzdiagramm in Abbildung 5 18 beschreibt den Ablauf dieser Initialisi
109. n In den Kapiteln zur Implementierung und Systembewertung wurden bereits einige n tige Weiterentwicklungen aufgezeigt Das waren u a dass Aber WSDL4J alle Attribute unterst tzt Formatierungen im Quelltext erhalten bleiben das Verhalten von iDoclt verbessert wird wenn die Quelldatei w hrend der Bearbeitung in iDoclt ge ndert wurde z B dynamisches Aktualisieren der Oberfl che mit automatischer Zuordnung der nderungen und dass vorhandene Dokumentationen von iDoclt behandelt und in sein Format berf hrt werden es gibt auch noch viele weitere m gliche Weiterentwicklungen die haupts chlich in die Richtung der besseren Benutzbarkeit von iDoclt gehen Vollst ndigkeitsanalyse von Dokumentationen In der Oberfl che soll die Vollst ndigkeit der Dokumentation visualisiert werden Das kann mit einer Prozentzahl geschehen die sich aus den empfohlenen thematischen Rollen und den davon bereits dokumentierten Rollen errechnet Zus tzlich k nnten die Symbole in dem Navigationsbaum f r die Schnittstellenelemente verschiedenfarbig gestaltet werden je nach Vollst ndigkeitsgrad der Dokumentation Es k nnte z B ein rotes Symbol verwendet werden wenn eine Operation noch nicht dokumentiert ist ein gelbes Symbol wenn mindestens eine Rolle aber noch nicht alle dokumentiert sind und ein gr nes Symbol wenn alle empfohlenen thematischen Rollen zugeordnet worden sind Exportfunktion Die Dokumentation soll aus de
110. n verwenden Wenn diese Fragments sich dann in das Host Plugin integrieren verwenden sie gemeinsam den Classloader des Host Plugins der dann den Konflikt feststellt und die Konflikt verursachenden Fragments nicht l dt Im Gegensatz dazu hat jedes Plugin Bundle seinen eigenen Classloader Das nachladen von jar Dateien kann dynamisch realisiert werden aber warum sollte man das sehr gute Konzept zum dynamischen Laden von Plugins von Eclipse vereinfacht nachprogrammieren wenn es einem bereits getestet zur Verf gung steht Weiterhin besteht hier wieder das gleiche Problem wie bei den Fragments dass 46 Vel 0 V OSGi Service Platform Core Specification 2009 Fragment Bundles S 74ff 51 5 2 Modularisierung und Erweiterbarkeit Klassenpfadkonflikte auftreten k nnen und zus tzlich Abh ngigkeiten z B zu weiteren Bibliotheken selbst aufgel st werden m ssen Auch das Konzept von Eclipse zur Bereitstellung von Plugins auf sogenannten Update Sites zusammen mit einem komfortablen Assistenten zur Installation und Deinstallation von Plugins kann dann nicht genutzt werden Bei der immer neu zu installierenden Programmversion ist man jedes Mal gezwungen den vollen Funktionsumfang zu installieren obwohl man vielleicht nur einen Teil ben tigt Das gleiche gilt wenn nderungen an einem Teil der Software vorgenommen werden Dann kann nicht ein Teil des Programms ausgetauscht werden sondern es muss immer das gesamte P
111. n Attribute eine Menge von Parameter ComplexType Damit ist auch gleich abgedeckt dass die Attribute selbst wieder einfache oder komplexe bzw strukturierte Typen sein k nnen Die meisten Elemente haben neben den strukturellen Komponenten auch weitere Attribute die mit dem Nichtterminal Atttributes exemplarisch dargestellt werden 43 5 1 Grammatiken sollen Die darin beschriebenen Elemente sind nicht vollst ndig enthalten aber u a einen Dokumentationsblock Documentation In Tabelle 5 3 ist die allgemeine Grammatik einer Schnittstellenstruktur in EBNF Erweiterte Backus Naur Form dargestellt Die Produktionsregeln definieren haupts chlich die abstrakte Struktur Attribute die zus tzlich f r die Implementierung ben tigt werden sind nicht enthalten z B die Attribute id und parent Sie werden zusammen mit der folgenden Klassenstruktur der allgemeinen Grammatik beschrieben Die in den Produktionsregeln der Grammatik gro geschriebenen W rter stellen Nichtterminalsymbole dar z B Interface und Operation Terminalsymbole sind in der vereinfachten Darstellung nur f r den Scope enthalten die klein geschriebenen W rter explicit und implicit Weitere Terminale w rden aus den Nichtterminalen Identifier String und SimpleType resultieren Letzter kann wegen der Abh ngigkeit zur verwendeten Programmier oder Beschreibungssprache nicht weiter spezifiziert werden m glich w ren z B long int xsd integ
112. n Dokumentationsblock durch die Klasse Documentation abgebildet ist Eine Documentation Klasse enth lt eine Menge von adressatenspezifischen Dokumentationen eine thematische Rolle ThematicRole und einen Sichtbarkeitsbereich Scope der implizit oder explizit sein kann Explizit soll f r sichtbare Schnittstellenelemente verwendet werden und implizit f r nicht sichtbare Elemente In dem Beispiel aus Kapitel 2 sind die gefundenen impliziten Elemente z B eine Datenquelle und eine Formel Als weitere Attribute hat es einen einfachen Bezeichner identifier einen qualifizierten Bezeichner qualifiedIdentifier mit Zusatz des Namensraum eine Kategorie category z B Operation oder Artifact ein Elternelement parent ein Flag ob eine Dokumentation dieses Elements erlaubt ist documentationAllowed und einer innerhalb einer InterfaceArtifact Struktur eindeutigen ID id Das statische Klassenattribut EMPTY SIGNATURE ELEMENT ist eine leere Instanz des SignatureElement s 46 5 1 Grammatiken das u a als Wurzel bzw Elternelement eines InterfaceArtifact s dient Das statische Klassenattribut ID_ COUNTER ist der Z hler der eindeutigen id de akra idocit structure SignatureElement o EMPTY SIGNATURE ELEMENT SignatureElement o ID COUNTER int category String id int identifier String documentation llowed boolean documentations List lt Documentation gt parent SignatureElement
113. n Eclipse nahtlos integriert Eine Alternative dazu ware z B ein eigenes Fenster basierend auf z B Java Swing Komponenten zu realisieren Dadurch wiirde aber das Konzept von Eclipse durchbrochen werden und eine nahtlose Integration w re nicht m glich Das SWT ist ein eigenst ndiges Open Source Toolkit von grafischen Steuerelementen f r Java Es bietet die effiziente und portable Nutzung der vom jeweils genutzten Betriebssystem zur Verf gung gestellten Elemente f r grafische Oberfl chen Der Editor soll in Eclipse ber das Kontextmen einer Datei ge ffnet werden k nnen In dem Editor der DocumentationEditor hei en soll soll dann die Baumstruktur eines InterfaceArtifact s abgebildet werden und die einzelnen Elemente des Baums dokumentiert werden k nnen In Abbildung 5 14 ist ein Layoutentwurf f r das UI zu sehen Es wurde nach dem POC UI Process Oriented Construction of User Interfaces Verfahren von der AKRA GmbH entwickelt Die POC UI Methode ist ein leichtgewichtiges Verfahren zur softwaretechnischen Strukturierung von grafischen Oberfl chen Aus den Anforderungen die erf llt werden sollen wurde das zu Grunde liegende Benutzungsmodell entwickelt 47 Vgl Krause Jan Christian Joneleit Kai Benjamin Prozessorientierte Konstruktion von Benutzeroberfl chen 2009 S 27 62 5 4 User Interface UI CustomerService java Select Signature Element Document Signature Element CustomerSe
114. n der Bachelorarbeit weswegen diese fiir die Parser Erweiterung fiir Java gew hlt wurde 6 3 2 Struktur der Dokumentation in Javadoc Die Dokumentationen von iDoclt sollen die Dokumentation von Javadoc erweitern Es soll also die Syntax und der Aufbau von Javadoc verwendet werden aber der Inhalt der Beschreibungen der bei Javadoc Freitext ist soll strukturiert werden Eine Strukturierung w re z B mit Javadoc Tags m glich die frei definiert werden k nnen Dadurch wiirde die Dokumentation aber sehr wahrscheinlich zu berfiillt von Tags werden Es miissten ftir jeden Dokumentationsblock Tags fiir den Elementpfad den Sichtbarkeitsbereich der thematischen Rolle und den Adressaten eingefiigt werden Javadoc unterst tzt auch HTML Formatierungen in den Beschreibungen Daher soll auf dieses Format zur ckgegriffen werden um die Dokumentationsbl cke darzustellen Eigentlich sollte auf HTML Formatierungen in Kommentaren verzichtet werden weil sie die Leserlichkeit der Kommentare im Quelltext verschlechtern k nnen und durch die zus tzlich eingebrachte Beschreibungssprache die Verst ndlichkeit erschweren kann Die Leser des Quelltextes m ssen dann nicht nur die eigentliche Programmiersprache Java und die Dokumentationen lesen und verstehen sondern auch noch HTML was keine Informationen enth lt sondern nur Formatierungen Trotzdem sollen die Dokumentationsbl cke in HTML formatiert werden weil sie dadurch einheitlich und bers
115. nden Version von iDoclt sollen bestehende Dokumentation eingelesen werden und in die Struktur der iDoclt Dokumentation berf hrt werden 69 Vgl Gosling James et al Java Language Specification 2005 Identifier S 19ff 96 6 4 User Interface UI 6 4 User Interface UI In diesem Kapitel wird das Zusammenspiel der UI Klassen und deren Realisierung n her beschrieben In Kapitel 5 4 wurde bereits erw hnt dass die Verwaltung der UI Klassen in der Klasse EditArtifactDocumentationComposite geschieht Durch die Nutzung des AKRA GUI Frameworks POC UI haben alle UI Klassen die gleichen Schnittstellen was das Arbeiten mit ihnen erheblich erleichtert Wie in Abbildung 6 7 zu sehen ist erben alle Klassen von der abstrakten POC UI Klasse AbsComposite die einheitliche Schnittstelle In der Methode initGUI werden die grafischen Komponenten der Klasse erstellt und soweit initialisiert wie es ohne einen definierten Zustand m glich ist In der Methode initListener werden die ben tigten Listener erzeugt um auf Ereignisse reagieren zu k nnen die von den anderen Komponenten gefeuert werden ber die Methode fireChangeEvent wird ein Ereignis ausgel st dass den lauschenden Komponenten mitteilt dass diese Komponente ver ndert worden ist und sich die anderen Komponenten ggf auch ndern sollten Mit der Methode addAllListener werden die initialisierten Listener den jeweiligen Komponenten hinzugef
116. nstructorModifier public protected private ConstructorDeclarator SimpleTypeName FormalParameterList Tabelle C 1 Auszug der Java Sprachspezifikation 3 Edition fiir eine Interface Deklaration in EBNF 75 Vel Gosling James et al Java Language Specification 2005 S 260ff 130 D Benutzerhandbuch D Benutzerhandbuch D 1 Systemvoraussetzungen Das Dokumentationswerkzeug iDoclt ist ein in Java entwickeltes Plugin f r Eclipse Es ben tigt eine installierte Version von e Eclipse 3 6 und e Java Runtime Environment JRE oder Java Development Kit JDK in der Version 1 6 bzw 6 F r das Ableiten der thematischen Raster aus einem Verb werden e das W rterbuch von WordNet in der Version 3 0 und e ein Model des Stanford Part Of Speech Taggers in der Version 3 0 ben tigt WordNet 3 0 kann von URL http wordnet princeton edu wordnet download heruntergeladen werden Dort w hlen Sie am besten Download tar gzipped WordNet 3 0 tar gz Den Stanford Part Of Speech Tagger in der Version 3 0 laden Sie bitte von der URL http nlp stanford edu software tagger shtml herunter Dort w hlen Sie Download basic English Stanford Tagger version 3 0 re entrant version 17 MB highly recommended Die Basic Version ist ausreichend da diese das ben tigte Model left3words wsj 0 18 tagger enth lt Alle weiteren Voraussetzungen leiten sich aus denen von Eclipse und Jav
117. nt boolean long rfaceType NormalClassDeclaration ExceptionType FormalParameterList VariableDeclaratorld char TypeVariable Interfaces Throws u LastFormalParameter VariableDeclaratorld Type VariableDeclaratorld NOY Jo float ArrayType EnumDeclaration fier ClassBody 129 C Java Interface Deklaration ClassModifier public protected private abstract static final Super extends ClassType Interfaces implements InterfaceType InterfaceType ClassBody ClassBodyDeclaration ClassBodyDeclaration ClassMemberDeclaration ConstructorDeclaration ClassMemberDeclaration MethodDeclaration FieldDeclaration ClassDeclaration InterfaceDeclaration ht r MethodDeclaration MethodHeader MethodBody MethodHeader MethodModifier ResultType MethodDeclarator Throws MethodModifier public protected private abstract static final synchronized FieldDeclaration FieldModifier Type VariableDeclarators VariableDeclarators VariableDeclarator VariableDeclarator VariableDeclarator VariableDeclaratorId Variablelnitializer VariableDeclaratorId Identifier VariableDeclaratorId ConstructorDeclaration ConstructorModifier ConstructorDeclarator Throws ConstructorBody Co
118. nt String interfaces 0 lt lt Java Class gt gt lt lt Java Class gt gt Javalnterface A de akra idocit java structure gt Interface de akra idocit structure o refToASTNode AbstractTypeDeclaration 0 operations 0 peral 0 innerinterfaces lt lt Java Class gt gt Zur JavaMethod A de akra idocit java structure gt 6 Op er ation de akra idocit structure a refToASTNode MethodDeclaration inputParamet outputParameters inputParameters exceptions O 1 0 0 1 lt Jawa Class gt gt lt Jawa Class gt gt JavaParameters gt G Parameters de akra idocit java structure de akra idocit structure parameters 0 lt lt Java Class gt lt lt Java Class gt JavaParameter gt G Parameter de akra idocit java structure de akra idocit structure Abbildung 6 6 Klassen der allgemeinen Schnittstellenstruktur fiir Java Der ASB der von den JDT aus einer Java Quelldatei erstellt wird ist der Ausgangspunkt um die allgemeine Schnittstellenstruktur eines Javalnterface Artifact s aufzubauen siehe Abbildung 6 6 Die erweiterten Klassen 6 3 Parser fiir Java JavalnterfaceArtifact Javalnterface und JavaMethod haben jeweils zus tzliche Attribute erhalten damit die Anderungen an den Dokumentationen an die richtigen Stellen des ASBs geschrieben werden k nnen In der Klasse JavaInterfaceArtifact h lt das Attribut compilationUnit eine Refe
119. nterfaceArtifact wieder gespeichert werden soll dann soll der InterfaceGenerator den neuen Quelltext generieren bzw den alten ndern Er soll f r jedes SignatureElement mit Hilfe des DocumentationGenerator s aus einer oder mehreren Listen von Documentation s einen Kommentarblock generieren und diesen zu dem richtigen Element im Quelltext schreiben Die 58 5 3 Parser fiir Schnittstellen Dokumentation eines Artefakts einer Schnittstelle und einer Operation sollen direkt an das Element geschrieben werden Die Dokumentation von Eingaben Ausgaben Fehlern und auch deren Attribute sollen in die Operationsdokumentation integriert werden Die einzelnen Dokumentationen sollen dabei so gekennzeichnet werden dass sie in dem Kontext der Operation eindeutig einem Element zugeordnet werden k nnen Das ist vor allem ftir das Wiedereinlesen der Dokumentation wichtig denn dabei m ssen die Dokumentationen der einzelnen Elemente wieder den richtigen SignatureElements zugeordnet werden Diese Kennzeichnung soll durch eine Pfadangabe von dem Parameter ausgehend zu dem dokumentierten Attribut erfolgen Der Pfad besteht aus einer Reihe von voll qualifizierten Namen zusammen mit dem jeweiligen ggf vorhandenen Datentyp Damit dieser Pfad eindeutig wieder geparst werden kann sind drei unterschiedliche Trennzeichen n tig die die einzelnen Informationen voneinander trennen Ein Trennzeichen um die Elemente in dem Pfad zu trennen eins um ein Element
120. nternet Biron Paul V Malhotra Ashok 2001 XML Schema Part 2 Datatypes Internet http www w3 org TR 2001 REC xmlschema 2 20010502 Stand 02 05 2001 Abruf 07 02 2011 Bray Tim et al 2000 Extensible Markup Language XML 1 0 Second Edition 2000 Internet http www w3 org TR 2000 WD xml 2e 200008 14 Stand 2000 Abruf 09 02 2011 Chinnici Roberto et al 2007 Web Services Description Language WSDL Version 2 0 Part 1 Core Language 2007 Internet http www w3 org TR 2007 REC wsdl20 20070626 Stand 2007 Abruf 11 01 2011 Christensen Erik et al 2001 Web Services Description Language WSDL 1 1 Internet http www w3 org TR 2001 NOTE wsdl 20010315 Stand 2001 Abruf 11 01 2011 Hamilton Graham 1997 JavaBeans API specification 1 01 Internet http www oracle com technetwork java javase documentation spec 136004 html Stand 08 08 1997 Abruf 10 02 2011 o V 2009 OSGi Service Platform Core Specification Release 4 Version 4 2 Internet http www osgi org download r4v42 r4 core pdf Stand Juni 2009 Abruf 26 02 2011 o V 0 J eBay Trading API Call Reference Internet http developer ebay com DevZone XML docs Reference eBay index html Version 699 Abruf 10 01 2011 o V 0 J eBay Trading API DetailLevelCodeType Internet http developer ebay com devzone xml docs reference ebay types DetailLevel CodeType html Version 705 Abruf 10 01 2011 142 Literaturverzeichnis o V 0
121. nvention beschrieben siehe Tabelle 7 3 Retrieves the accumulated feedback left for a specified user or the summary feedback data for a specific transaction or item return The FeedbackDetailType object E public FeedbackDetailType getFeedback Tabelle 7 3 Ausgef lltes Javadoc Raster f r get Feedback Ein Entwickler k nnte mit dieser Beschreibung das Feedback f r einen Benutzer nicht abrufen Es fehlen viele n tige Informationen wie die Einstellungen von der Datenquelle aber auch Konfiguration der Klasse bzw fiir den Aufruf der Methode Der Autor muss sich selbst erarbeiten was alles ben tigt wird um mit der Klasse bzw Methode zu arbeiten Dieses muss er dann im Freitext beschreiben 7 2 Realisierung der Anforderungen Wie u a in dem vorherigen Kapitel gesehen werden kann realisiert iDoclt fast vollst ndig die allgemeinen Anforderungen an eine Schnittstellendokumentation aus Kapitel 3 1 Folgendes kann in iDoclt dokumentiert werden Eingaben e Ausgaben e Ausnahmen Fehler e Konfigurationsm glichkeiten z B von Datenbankverbindungen oder die Verwendung unterschiedlicher Algorithmen 110 7 2 Realisierung der Anforderungen Das Werkzeug unterstiitzt aber nicht direkt das Referenzieren Verlinkung der Dokumentation von Datentypen oder Metadaten wie z B eine Versionsnummer Da sich iDoclIt aber haupts chlich in eine bestehende Dokumentationsm glichke
122. okumentierenden Programmier oder Beschreibungssprache braucht Diese Teile sind daher pr destiniert wiederverwendet zu werden Ein Werkzeug sollte also um weitere Programmier und Beschreibungssprachen erweiterbar sein Die Oberfl che und die Logik der thematischen Raster soll dabei wiederverwendet werden 27 3 4 Vorgaben der AKRA GmbH 3 4 Vorgaben der AKRA GmbH Entwicklungsschwerpunkte bei der AKRA GmbH liegen u a bei Java und Webservices Als Entwicklungsumgebung wird daf r haupts chlich Eclipse eingesetzt Daher liegt ein besonderes Interesse bei der Dokumentation von Java Quelltexten und Schnittstellenspezifikationen von Webservices in der Webservice Description Language WSDL sowie die Integration eines Werkzeugs in die Entwicklungsumgebung Eclipse Bei der AKRA GmbH wird ausschlie lich in Englisch entwickelt daher soll sich die Verbanalyse f r die thematischen Raster auf englische Verben beschr nken Die Komponente zum Ableiten der thematischen Raster ThematicGridService wird von Herrn Krause vorgegeben 32 Siehe o V Eclipse 0 J 28 4 Existierende Dokumentationssysteme 4 Existierende Dokumentationssysteme Es existieren viele ver ffentlichte Dokumentationssysteme In diesem Kapitel werden eine Auswahl von 19 solcher Systeme exemplarisch betrachtet die eigens f r diese Evaluierung im Internet recherchiert wurden Aus den Eigenschaften der betrachteten Dokumentationssystemen werden zun c
123. omposite zum Entfernen einer Documentations nase aa 102 Tabelle 7 1 Definierte thematische Raster f r das Fallbeispiel 105 Tabelle 7 2 Javadoc Raster f r getFeedback ueresssenennnseneeneenennnen 110 Tabelle 7 3 Ausgef lltes Javadoc Raster f r getFeedback eee 110 Tabelle A 1 Kategorien und allgemeine Informationen zu den untersuchten Dokumentationssystemen nen aan 120 Tabelle A 2 Unterst tzte Dokumentationstypisierungen von den untersuchten Dokumentatisnssystemien ties 121 Tabelle A 3 Fortsetzung Unterst tzte Dokumentationstypisierungen von den untersuchten DokumentatiONSSYSteMEN ooocoocccoococonoconnconnnconnnonconnnnnnns 122 Tabelle A 4 Unterstiitzung nicht sichtbarer Elemente von den untersuchten DORUMENTATIONSS oa 123 Tabelle A 5 Unterstiitzte Programmier und Beschreibungssprachen von den untersuchten DokumentatiONSSYSteMEN ooccoocccoococonoconcconanconnnocconnnonns 124 Tabelle A 6 Links zu den untersuchten Dokumentationssystemen ee 125 Tabelle B 1 WSDL 1 1 Spezia 126 Tabelle B 2 Fortsetzung WSDL 1 1 SpezifikatiOM oooocnnccnnnncnnoccnonnconnconnconnccnnnos 127 Tabelle C 1 Auszug der Java Sprachspezifikation 3 Edition f r eine Interface Deklaration in EBNR aussehen 130 Abbildungsverzeichnis Abbildung 2 1 Rauschen in der O Doku am Beispiel des Eingabeparameters ItemID der Operation GetFeedback aus der eBay Trading AP
124. onnnconoccnooccoonnconncconaconannncnnnnos 89 6 3 3 Implementierungsdetails des Java Parsers nneen 91 6 4 User Interface Ucn e So nee ae ela OS 97 7 Systembewertung aussi id a sbuendevseasvoidereedens 103 71 Fallbeispiel A O A 103 7 1 1 Dokumentation mit Dock ae 104 7 1 2 Dokumentation mit Eclipse und Javadoc eesnennnnnn 109 7 2 Realisierung der Anforderungen san 110 7 3 Probleme desProt typen re esse di na 112 VA DAA A ee 113 MIE AAA 116 8 1 Zusammenfassung und Ausblick 116 8 2 M gliche Weiterentwiekl ngen u a an 118 A Auswahl existierender Dokumentationssysteme sssssssoossssossssnsssssnnnsnsnsnsnnnene 120 B WSDL 1 1 Spezifikation u anni snernne 126 C Java Interface Deklarationi isis iccccssccessiicecorscsvssacesdsececensascosedscesedecsvecssndeecasseacsees 128 D Benutzerhandbuch u a RR 131 DE1 Systemvoraussezungen a ae Erin 131 A se E E T 132 D 3 Bedienines ani ta tra 132 D 3 1 Konfiguration voniDo iii 132 D 3 2 Erstellen von DokumentatiONeN oooconoccnoccnionnconncconoconncononnnoconnncnnconnnono 135 BAbkurzungsverzeichnns essen 139 Literaturverzeichns cion asia 141 Eidesstattliche Briar une iscsessosissssdessiosoosessoussdcovecscsusesvonsisvonsesescacsctassesensisouusoaios 145 Tabellenverzeichnis Tabelle 2 1 Auszug aus der Schnittstellenbeschreibung der Operation GetFeedback aus der eBay Trading AP tdo 14 Tabelle 2 2 Beispiel eines thematischen Rasters f
125. ons gt Element das lt portType gt lt message gt und lt types gt Element analysieren Dokumentationen werden aber nur in das lt definitions gt Element und die einzelnen Elemente vom lt portType gt eingef gt 81 6 2 Parser fiir WSDL lt wsdl definitions name nmtoken targetNamespace uri gt lt wsdl documentation gt lt wsdl types gt lt wsdl documentation gt lt xsd schema gt lt wsdl types gt lt wsdl message name nmtoken gt lt wsdl documentation gt lt part name nmtoken element qname type qname gt lt wsdl message gt lt wsdl portType name nmtoken gt lt wsdl documentation gt lt wsdl operation name nmtoken gt lt wsdl documentation gt lt wsdl input name nmtoken message qname gt lt wsdl documentation gt lt wsdl input gt lt wsdl output name nmtoken message qname gt lt wsdl documentation gt lt wsdl output gt lt wsdl fault name nmtoken message qname gt lt wsdl documentation gt lt wsdl fault gt lt wsdl operation gt lt wsdl portType gt lt wsdl definitions gt Tabelle 6 6 Auszug aus WSDL 1 1 Spezifikation gt Das Analysieren und berf hren der Elemente in eine Objektstruktur bernimmt WSDL4J Aus der resultierenden Objektstruktur wird dann die InterfaceArtifact Struktur auf
126. orm Core entstehen Man beachte den Unterschied dass einmal der Parameterbezeichner customer und einmal der Ergebnistyp Customer in dem Pfad der den Kontext der Elemente beschreibt vorkommt Eine aktive Einbeziehung der Elementumgebung w hrend der Laufzeit ist nicht m glich da die Struktur doppelt verkettet ist Z B bei einem Test auf Gleichheit eines Elements mit einem anderen wiirde ein Element seine Umgebung also wegen der Doppelverkettung seine Vorg nger und seine Nachfolger in die Gleichheitspr fung mit einbeziehen Die Vorg nger und Nachfolger verwenden den gleichen Algorithmus Somit w rden sie auch das Ausgangselement mit in ihre Gleichheitspr fung einbeziehen wodurch alles wieder von vorne beginnen w rde Der Gleichheitstest w rde daher in einer Endlosschleife enden Eine Alternative w re die passive Bestimmung der Elementumgebung Dabei w rde jedes SignatureElement ein Attribut erhalten das den Kontext beschreibt beispielsweise den Pfad vom InterfaceArtifact die Wurzel bis zum Element Dann w re jedes SignatureElement mit diesem Attribut eindeutig identifizierbar Die Nutzung einer ID bezweckt das gleiche Dabei hat ein Attribut vom Java Datentyp int die gro en Vorteile dass es sehr viel performanter und speicherplatzsparender ist ben tigt vier Byte als eine Zeichenkette Java String in der jedes Zeichen zwei Byte gro ist plus den Overhead des Objekts Das SignatureElement enth
127. osii teSelection select tItemComposite ticRoleList tDocumentat tAddresseeList add tThematicRolel selection set selection set selection set docItemComp set new DocumentItemCompositeSelect tion document DocumentItemComposite docItemComp new DocumentItemComposite tSelection select List this rootComposite SWT NON this documentI Button delete deleteButton set this documentItemComposite tText X documentation to display list of all Addressees list of all ThematicRoles tion tion tion List thematicRoleList Ed temCompositeList add docItemComp new Button this rootComposite SWT PUSH Deletel ButtonList add deleteButton Tabelle 6 11 Auszug der Methode aus der Klasse Document ItemListComposite zum Hinzuf gen einer Documentation Document ItemComposite Wenn auf eines der Entfernen Schaltflachen zu einem DocumentItemComposite geklickt wird wird der Index der Schaltfl che in der Liste bestimmt und danach das Documentation mit dem gleichen Index aus der Liste des Selection Objekts entfernt siehe Tabelle 6 12 fireChangeEvent bekannt gemacht Danach wird die nderung wieder ber 6 4 User Interface UI private void documentationItemCompositeDeleteButtonClicked SelectionEvent e get index of the clicked delete button int row
128. r grafischen Oberfl che heraus in ein anderes Format exportiert werden Das Format k nnte z B DITA oder DocBook sein wof r wiederum viele Exportvarianten existieren 118 8 2 M gliche Weiterentwicklungen Uber dieses Zwischen Format kann die Dokumentation in viele andere Formate exportiert werden wie z B HTML und PDF e Schnelleres Dokumentieren mit iDoclt Hierbei soll das Benutzungs modell erweitert werden damit ein Autor schneller eine Dokumentation erstellen kann o Dokumentieren im Quelltexteditor Bei dieser Variante kann der Autor z B in dem Java Editor in Eclipse ber ein Tastenk rzel oder dem Kontextmen ein kleines Fenster 6ffnen das die Dokumentationsfelder nur f r eine Methode enth lt Dadurch kann die Dokumentation f r eine Methode schnell erfasst werden was i d R von Entwicklern als positiv angesehen wird Falls doch mehr dokumentiert werden soll m sste der vollst ndige iDoclt Editor ge ffnet werden Sichtbare Elemente einer Methode zusammen dokumentieren In der Oberfl che sollen die sichtbaren Elemente einer Methodensignatur in einem Fenster angezeigt werden wenn eine Methode selektiert wurde Die sichtbaren Elemente sich die am h ufigsten dokumentierten Elemente die dann in einem Fenster dokumentiert werden Dadurch wird dem Autor das Navigieren durch den Navigationsbaum der Schnittstellenelemente erspart e Rollenabhangige Editoren F r die Erfassung der Dokumentationen
129. r nur f r den ersten Rekursionsschritt berpr ft werden Die Wiederholungen der Definition sollen nicht in der allgemeinen Struktur ber cksichtigt werden da sie keine neuen Attribut bzw Typinformationen liefern Ein generelles Problem das auftreten kann ist wenn die Quelldatei artefakt w hrend der Bearbeitung mit iDoclt von anderen Programmen ge ndert wird Hierf r existieren mehrere L sungen Um herauszufinden ob eine Datei ge ndert 60 5 3 Parser fiir Schnittstellen wurde kann sie berwacht werden w hrend sie in iDoclt ge ffnet ist Alternativ kann beim Offnen der Datei z B eine Priifsumme erzeugt und gespeichert werden die vor dem Speichern wieder berpr ft wird Mit Hilfe dieser Ma nahmen kann erkannt werden ob eine ge ffnete Datei in der Zwischenzeit ge ndert wurde Wenn sie ge ndert wurde gibt es wieder mehrere M glichkeiten wie darauf reagiert werden kann Die in iDocIt gemachten nderungen k nnen e verworfen werden und der neue Stand der Datei bleibt erhalten e der neue Stand wird mit den nderungen berschrieben oder e es wird versucht die Anderungen mit dem neuen Stand zu verschmelzen Die ersten beiden M glichkeiten sind die einfachsten F r einen Benutzer von iDoclt wird es aber frustrierend sein wenn seine Arbeit einfach verworfen wird und er noch einmal neu anfangen muss F r die zweite Variante ist es noch nicht einmal notwendig zu wissen ob die Datei in der Zwischenzeit ge
130. rIDType Tabelle 5 5 Pfad von der WSDL Message GetFeedbackRequest der Operation GetFeedback aus der eBay Trading API bis zum Attribut UserID vom Typ UserIDType Die Attribute der Typen von Operationsparametern Eingaben Ausgaben und Fehler sollen soweit ber cksichtigt werden wie sie verf gbar nach au en sichtbar und nicht rekursiv sind Wenn sie nicht verf gbar also deren Deklaration nicht zugreifbar ist sollen sie ignoriert werden Das kann z B bei der WSDL f r Typen passieren die in einem externen XML Schema definiert sind F r Java kann dieses aber z B nicht passieren denn dort m ssen alle Typen immer bekannt und verf gbar sein Wenn Attribute nicht nach au en sichtbar sind sollen sie auch ignoriert werden Dieses gilt z B f r private Attribute in einer Java Klasse die keine Getter oder Setter Methode haben Sie werden dann nicht weiter in der allgemeinen Struktur aufgef hrt Da bei der WSDL alle Elemente ffentlich sichtbar sind hat diese Restriktion dort keinen Effekt Geerbte Attribute aus einer Oberklasse sollen in der Struktur wie ein einzelnes Attribut vom Typ der Oberklasse aufgef hrt werden Der Bezeichner f r dieses zus tzliche Attribut soll entsprechend der Programmier bzw Beschreibungssprache gew hlt werden und stets eindeutig unter den Attributen sein in Java z B der Bezeichner super das ein reserviertes Schl sselwort ist Wenn der Typ eines Attributs rekursiv definiert ist soll e
131. rationswerte von DetailLevelCodeType aus der eBay Trading APP Schnittstellenelement Dokumentation Operation GetFeedback Eingabeparameter DetailLevelCodeType DetailLevel Applicable values Returnall Not all values in DetailLevelCodeType apply to this field Tabelle 3 3 Auszug aus der Schnittstellenbeschreibung der Operation GetFeedback aus der eBay Trading API Der erste Satz der Beschreibung zu dem Wert ReturnSummary enth lt die Bedeutung des Wertes Die folgende Beschreibung enth lt kontextspezifische Verhaltensweisen die bei der allgemeinen Beschreibung nicht stehen sollte In Tabelle 3 3 sieht man dass in der Dokumentation von GetFeedback textuell verfasst ist dass nur der Wert ReturnAll anwendbar ist Nach dem Dokumentationsprinzip der thematischen Rollen wiirde z B die Rolle CRITERION dem Attribut DetailLevel zugeordnet werden und als Beschreibung dass nur der Wert ReturnAll erlaubt ist Die zus tzliche Dokumentation in der Enumeration w rde entfallen Mit Anwendung dieses Prinzips werden Dokumentationen dort gepflegt wo sie Anwendung finden und bl hen die allgemeine Dokumentation eines Elements nicht unn tig auf 30 Vel o V eBay Trading API DetailLevelCodeType o J 31 Vgl 0 V eBay Trading API o J GetFeedback 26 3 3 Dokumentationswerkzeug Ein Dokumentationswerkzeug sollte eine Dokumentation direkt in der Quelldatei speiche
132. rchitektur f r Softwaresysteme siehe Abbildung 5 7 so befindet sich das UI in der Pr sentationsschicht die Core Komponente in der Fachkonzeptschicht und die Parser Erweiterungen Parser Extension zur H lfte in der Fachkonzeptschicht und zur H lfte in der Datenhaltungsschicht Zur Vollst ndigkeit ist in der Datenhaltungsschicht auch ein Artefakt eine Quelldatei aufgef hrt Die Parser Erweiterungen enthalten nicht nur Operationen zum Lesen und Speichern von Daten aus einer Datei sondern auch die Logik zum Uberf hren der eingelesenen Schnittstellenstruktur in die allgemeine Schnittstellenstruktur Deswegen sind sie nicht eindeutig einer Schicht zuordenbar 53 5 2 Modularisierung und Erweiterbarkeit User Interface UI Pr sentationsschicht y Core Services Y Parser Extension Y Artifact File Fachkonzeptschicht Datenhaltungsschicht Abbildung 5 7 Einordnung der iDoclt Komponenten in die Drei Schichten Architektur Die Core Komponente stellt f r die Kommunikation einige Dienste zur Verf gung Zum einen in der Klasse ThematicGridService siehe Abbildung 5 8 die Logik f r die thematischen Raster die von Herrn Krause implementiert wurde als auch Dienste zum Laden und Speichern von Schnittstellendateien in der Klasse PersistenceService siehe Abbildung 5 9 de akra idocit services ThematicGridService O
133. ren und pr gnanteren Dokumentationen soll in der Projektarbeit die Einarbeitung von Mitarbeitern erleichtert werden Die grafische Oberfl che von iDoclt erm glicht Autoren die nicht in Quelltexten direkt arbeiten m chten Dokumentationen zu erstellen Diese Bachelorarbeit hat einen Prototypen als Ergebnis f r den es noch viele Weiterentwicklungsm glichkeiten und Potential gibt Die AKRA GmbH kann ihre Mitarbeiter in diesem Ansatz und dem Werkzeug schulen damit diese einen Vorteil im Projektgesch ft geltend machen k nnen IDoclt er ffnet f r die AKRA GmbH aber auch einen v llig neuen Gesch ftszweig Documentation Consulting Sie k nnte Dienstleistungen f r die Erstellung von APIs und deren Dokumentationen anbieten Auch Audits bestehender API Dokumentation w ren eine neue denkbare Dienstleistung Wie in der Motivation der Bachelorarbeit erw hnt wird iDoclt als Open Source Projekt publiziert Der Ansatz und iDoclt sollen daher in Artikeln von bekannten Zeitschriften bekannt gemacht werden und die Software weiter verbessert werden U a interessierte Unternehmen k nnen dann Parser Erweiterungen f r ihre Zwecke entwickeln und auf der Projektseite von iDoclt http code google com p idocit ver ffentlichen Die gew hlte Modularisierung von iDoclt soll dieses Vorgehen und die verteilte Weiterentwicklung vorantreiben 117 8 2 M gliche Weiterentwicklungen 8 2 M gliche Weiterentwicklunge
134. renz zur Repr sentation der geparsten Datei als ASB und das Attribut originalDocument enth lt die String Repr sentation des unver nderten Inhalts der geparsten Datei Das zweite Attribut wird beim Speichern ben tigt denn die CompilationUnit merkt sich nur die nderungen die daran gemacht werden Vor dem Zur ckschreiben in die Datei werden die nderungen in den Originalinhalt eingepflegt und dann alles in die Datei geschrieben Die Klassen Javalnterface und JavaMethod haben jeweils eine Referenz auf das entsprechende AbstractTypeDeclaration z B InterfaceDeclaration oder Class Declaration und MethodDeclaration Die Klassen JavaParameters und JavaParameter haben keine weiteren Attribute erhalten weil zu JavaParameters keine Dokumentation erfasst werden kann und die Dokumentation von JavaParameter wird mit in die der JavaMethod integriert Die Klasse JavaParameters ist hier nur ein Container ftir eine Menge von JavaParameter sie hat kein korrespondierendes Element in der Java Sprachspezifikation In der Java Parser Erweiterung kommt zum ersten Mal das Attribut documentationAllowed vom SignatureElement siehe Abbildung 5 5 S 47 zum Einsatz ber dieses Attribut wird gesteuert ob f r ein SignatureElement eine Dokumentation in dem UI erstellt werden kann Die Klassen JavalnterfaceArtifact und JavaParameters haben keine korrespon dierenden Elemente in der Java Sprachspezifikation Dah
135. rn Dadurch k nnen inkonsistente Versionsst nde und die Portierung zwischen verschiedenen Systemen Entwicklungsumgebung bzw Quelldatei und z B einem Redaktionssystem bestm glich vermieden werden Hierbei ist es aber wichtig dass die Quelldatei nur um die Dokumentation ver ndert wird und nicht die Semantik des Inhalts Au erdem soll sich das Werkzeug direkt in eine Entwicklungsumgebung integrieren Die Dokumentation von Schnittstellen l sst sich dadurch besser in den Entwicklungsprozess einbinden Durch das st ndige Wechseln zwischen verschiedenen Programmen Entwicklungsumgebung und Redaktionssystem w rde es immer einen Bruch in dem Entwicklungsprozess geben Auch ein Dokumentationsautor der sich mit Quelltexten nicht so gut auskennt soll das Dokumentationswerkzeug nutzen k nnen ber eine grafische Oberfl che soll er die Schnittstellenelemente mit den oben beschriebenen Dokumentationsbl cken dokumentieren k nnen F r ein aus einem Operationsbezeichner extrahiertes Verb soll das Werkzeug das thematische Raster ableiten und in der Oberfl che anzeigen Der Dokumentationsansatz ist unabh ngig von einer Programmier oder Beschreibungssprache Sie muss lediglich eine Art von Kommentar im Quelltext erlauben damit die Dokumentation gespeichert werden kann und Schnittstellen mit Operationen beinhalten F r die Dokumentation werden immer die gleichen Informationen erfasst weswegen die grafische Oberfl che auch keine Bindung zur d
136. rogramm neu installiert werden Das kann den Umgang mit dem Programm unpraktisch machen Au erdem ist die Verwaltung von vielen Entwicklern die an einem gro en Plugin arbeiten schwieriger als wenn sie so gut wie m glich unabh ngig kleinere Plugins entwickeln Auch der Verwaltungsumfang f r den Programmcode steigt bei einem gro en Programm wenn immer wieder Teile neue Parser Erweiterungen integriert werden m ssen Auch wenn es mehrere M glichkeiten zur Erweiterung von Eclipse Plugins gibt ist es f r iDoclt sinnvoll das Konzept der Extension Points und Extensions einzusetzen Dadurch k nnen s mtliche Vorteile die Plugins und Eclipse bieten genutzt werden Abbildung 5 6 zeigt die Einteilung der Komponenten von iDoclt unter Verwendung des Konzeptes der Extension Points Die grafische Oberfl che UI soll sich als Editor in Eclipse integrieren die eine feste Abh ngigkeit zur Core Komponente Plattform mit Diensten von iDoclt erhalten soll Diese Core Komponente ist das Bindeglied zwischen dem UI und den Parser Erweiterungen Parser Extension 52 5 2 Modularisierung und Erweiterbarkeit lt lt component gt gt Core Services 2 Parser Extension Point lt lt component gt gt 8 Extended Interface Artifact Structure lt lt component gt gt Extension A Abbildung 5 6 Komponentendiagramm von iDoclt Betrachtet man die einzelnen Komponenten in der Drei Schichten A
137. rvice java Artifact Add Documentationblock CustomerService Interface find Operation Thematic Role ACTION Scope EXPLICIT w Parameters Customer Type Customer Developer Architect Tester Manager CD id Type int name Type String e address Type Address ReturnType Customer Type Customer delete Operation create Operation Finds a customer by its id Thematic Role SOURCE Scope IMPLICIT ws Overview of recommended roles for Signature Element i loper itect T Manager i Searching Operations R ACTION Associated Searchs in the company s customer database SOURCE Associated AGENT CRITERION OBJECT 2 Abbildung 5 14 Layoutentwurf des User Interfaces Im Folgenden werden die Zust ndigkeiten der in Abbildung 5 14 durchnummerierten Komponenten kurz skizziert Jedes Element SignatureElement im InterfaceArtifact soll mit beliebig vielen Dokumentationsbl cken dokumentiert werden k nnen Da das InterfaceArtifact eine Baumstruktur bildet braucht das UI eine Komponente mit der durch diese Baumstruktur navigiert werden kann Diese Komponente soll SelectSignatureElementComposite 1 hei en Wenn auf ein Element in diesem Baum geklickt wird sollen die bereits vorhandenen Dokumentationsbl cke f r dieses SignatureElement in einer Liste angezeigt werden Zu dieser Liste sollen weitere Bl cke hinzugef gt aber auch vorhandene entfernt werden k nnen
138. rweiterung eines fest spezifizierten Host Plugins 50 5 2 Modularisierung und Erweiterbarkeit e Nachladen von Dateien Beim Nachladen von Dateien w rde man z B aus einem definierten Ordner alle oder nur bestimmte Dateien z B jar Dateien laden und dann deren bereitgestellte Funktionalit t nutzen Diese Dateien m ssen dabei bestimmte Anforderungen z B implementierte Schnittstellen erf llen damit sie auch verwendet werden k nnen e Neue Programmversion Bei dieser Variante w rde eine bestehende Installation des Programms immer durch eine komplett neue Programmversionen ersetzt werden um neue Funktionalit ten zu erhalten Die Plugin Fragments k nnen zwar dazu verwendet werden Programm funktionalit ten einem Plugin hinzuzuf gen das Core Plugin k nnte der Host f r die Parser Erweiterungen Fragments sein sie sind aber erstens nicht zu diesem Zweck entwickelt worden Sie sind eher dazu gedacht abh ngig vom Betriebssystem verschiedene Bibliotheken zu laden oder um Sprachversionen zu erm glichen also nur kleine Programmver nderungen Zweitens ist im Zuge der Ver ffentlichung von iDoclt als Open Source Projekt angedacht dass Parser Erweiterungen verteilt entwickelt werden Dadurch k nnen bei der Verwendung von Fragments Klassenpfadkonflikte auftreten Unterschiedliche Entwickler k nnen in verschiedenen Parser Erweiterungen gleich benannte Klassen und gleiche Bibliotheken vielleicht auch in verschiedenen Versione
139. ser public boolean isFreeAccount return freeAccount public void setFreeAccount boolean free freeAccount free public int getId return id public int getUser return user public void setUser User u user u Tabelle 6 10 Beispiel einer Java Klasse zur Erl uterung der JavaBeans Spezifikation 66 Vel Anhang C 67 Vgl Hamilton Graham JavaBeans 1997 Accessor methods S 40 68 Vgl Hamilton Graham JavaBeans 1997 Simple properties Boolean properties S 55 93 6 3 Parser fiir Java In Tabelle 6 10 ist dieses exemplarisch fiir die Attribute id und user dargestellt Bei einem Attribut vom Typ boolean f ngt der Getter mit is an gefolgt von dem gro geschriebenen Bezeichner isFreeAccount Die Setter folgen dem gleichen Muster fangen nur immer mit set an In dem Beispiel in Tabelle 6 10 sind die Attribute id user und freeAccount nach der JavaBeans Spezifikation nach au en sichtbar und w rden vom Parser ber cksichtigt werden Das public Attribut enabled ist zwar nach der Java Spezifikation nach au en sichtbar wird aber nicht ber cksichtigt weil es keinen Getter und oder Setter nach der JavaBeans Spezifikation hat lt sJava Class gt gt JavalnterfaceArtifact lt Jaya Class gt de akra idocit java structure gt G InterfaceArtifact compilationUnit CompilationUnit de akra idocit structure originalDocume
140. ser Untersuchung 1 2 Ziele und Gang dieser Untersuchung Im Rahmen dieser Bachelorarbeit wird untersucht wie ein Autor beim Verfassen von O Doku technisch unterst tzt werden kann Grundlage f r diese Untersuchung ist der Ansatz von Krause Operationen mit Hilfe von thematischen Rastern zu dokumentieren Zun chst wird der Ansatz von Krause beschrieben und gezeigt wie damit Operationen dokumentiert werden k nnen Daraus werden Anforderungen an Dokumentationswerkzeuge und formate abgeleitet und existierende Werkzeuge und Formate auf diese hin evaluiert Da kein Werkzeug alle Anforderungen erf llt wird ein neues prototypisches Werkzeug mit dem Namen iDoclt entworfen und implementiert Anschlie end werden Potential und L cken des neu entwickelten Werkzeugs anhand eines Fallbeispiels gezeigt Diese Arbeit schlie t mit einer Zusammenfassung und einem Ausblick sowie einigen m glichen Weiterentwicklungen die u a die t gliche Arbeit mit iDoclt erleichtern sollen 6 Vgl Krause Jan Christian Thematic Grids 2010 7 Vgl Krause Jan Christian Stille und Rauschen 2011 11 2 Dokumentation von Operationen mit thematischen Rastern 2 Dokumentation von Operationen mit thematischen Rastern In der Praxis werden in der Regel die ffentlich sichtbaren Elemente einer Operationssignatur z B Eingaben Ausgaben und Ausnahmen bzw Fehler dokumentiert Eine O Doku gilt als vollst ndig wenn jedes Element einmal dokumen
141. sichtbare Elemente die aber zum Vertrag der Schnittstelle bzw Operation geh ren Fiir diese Elemente herrscht haufig Stille in der O Doku weil diese von Dokumentationswerkzeugen z B Javadoc nicht im Raster zur Dokumentation zur Verf gung gestellt werden Wenn die SOURCE als Parameter in die Operation hineingehen wiirde ware es ein in der Signatur explizit angegebenes Element und wiirde im Javadoc Raster mit aufgefiihrt werden Aber da Datenbankverbindungen u 4 in der Regel im Hintergrund verwaltet werden ist diese Vorgehensweise in der Praxis eher selten anzutreffen Die SOURCE sollte aber dokumentiert werden weil das Ergebnis der Operation ma geblich von der implizit verwendeten Ressource abh ngt Beispielsweise bietet eBay Entwicklern neben dem Produktivsystem auch eine simulierte Sandbox Umgebung zum Testen ihrer entwickelten Programme an Weiterhin sollte auch die Berechnungsformel FORMULA fiir die Bewertungskennzahl in der O Doku enthalten sein Sie beschreibt das Ergebnis der Operation und soll auch als Spezifizierung des Soll Verhaltens dienen siehe Kapitel 1 1 In der Dokumentation der eBay Trading API fiir Get Feedback ist sie aber nicht enthalten sondern lediglich in der Benutzerhilfe von eBay 22 Vel 0 V eBay Developer s Sandbox o J 23 Vel 0 V eBay help How Feedback works o J How are Feedback scores calculated 16 2 Dokumentation von Operationen mit thematischen Rastern
142. sie dieses f r einen bestimmten Benutzer oder Artikel Es soll daher haupts chlich nach dem Raster Calculating Operations dokumentiert werden aber 106 7 1 Fallbeispiel auch die Rolle PRIMARY KEY aus dem Raster Searching Operations soll ber cksichtigt werden Beim Klick in iDoclt auf die Methode getFeedback werden also die thematischen Raster angezeigt und diese sollen den Elementen der Methode zugeordnet werden und auch beschrieben werden Select Signature Element Document Signature Element getFeedback Method E GetFeedbackCall java Artifact A Add Thematic Role documentation S O GetFeedbackcall Class H GetFeedbackCall Constructor Thematic Role ACTION v Scope EXPLICIT v H get E z _ p gt Ek en Analyst Builder Integrater Tester Developer shy GES Retumtype Retrieves the accumulated Feedback left F ified r etrieves the accumulated feedback left For a specified user lt gt FeedbackDetailType or the summary feedback data for a specific transaction or amp Throws item 4 getUserID Method u H setUserID Method 4 getItemID Method setItemID Method My lt j Mm gt Thematic Role FORMULA v Scope IMPLICIT v Overview of recommended roles For getFeedback l Analyst Builder Integrater Tester Developer a Calculating Operations A Look ACTION Associated 3 at http pages ebay com help feedback howitworks
143. ssee gt signature lt addressee group Developer gt lt addressee gt lt docpart gt lt docpart role PRIMARY KEY signatureElement UserID UserIDType gt 4 lt addressee group Developer gt lt addressee gt lt docpart gt lt wsdl documentation gt lt wsdl input gt lt wsdl output message GetFeedbackResponse gt lt wsdl documentation gt lt wsdl documentation gt 5 lt wsdl operation gt lt wsdl portType gt Tabelle 6 7 Zuordnung der iDoclt Dokumentationsbl cke in die WSDL der eBay Trading API 86 6 3 Parser fiir Java 6 3 Parser fur Java Die Parser Erweiterungen fiir Java ist unter der geforderten Pr misse entwickelt worden dass die Quelldatei nur um die Dokumentation ver ndert wird D h dass der vorhandene Inhalt bestehen bleiben soll sodass der Programmcode nicht ver ndert wird Unterschiedliche Formatierungen z B Leerzeichen und Zeilenumbr che ver ndern bei Java nicht den Programmcode da es beispielsweise in Bl cke und Anweisungen die mit einem Semikolon beendet werden aufgeteilt ist Eine Ver nderung des Formats ist demnach nicht entscheidend aber sie sollte trotzdem bestm glich vermieden werden In z B einer Versionskontrolle sollen bei einem Dateivergleich nur die wichtigen nderungen ber cksichtigt werden Unn tige Format nderungen sollen diese nicht berlagern und auch nicht zu unn tig vielen Datei nderungen f
144. szug der Klasse WSDLMessage 6 1 2 Parser Extension Point Plugins k nnen in Eclipse w hrend der Laufzeit installiert gestartet gestoppt und deinstalliert werden Die Parser Erweiterungen k nnen sich demnach w hrend der Laufzeit an dem Extension Point der Plattform an und abmelden Daher muss diese darauf reagieren k nnen Eine M glichkeit w re die angemeldeten Parser Extensions einmal von Eclipse abzufragen und zwischenzuspeichern Dann muss aber auch ein Listener bei Eclipse registriert werden Der Listener reagiert dann auf neue und deinstallierte Extensions und aktualisiert den Zwischenspeicher Eine andere M glichkeit w re die Extensions jedes Mal neu von Eclipse abzufragen wenn sie ben tigt werden F r diese Bachelorarbeit wurde die zweite Variante realisiert Eine Parser Extension wird nur beim Laden und Speichern einer Datei ben tigt Daher fallen die wenigen Aufrufe die dadurch mehr entstehen als wenn sie zwischengespeichert werden w rden nicht ins Gewicht Dadurch wird aber der zus tzliche Verwaltungsaufwand des Zwischenspeichers gespart 75 6 2 Parser fiir WSDL 6 2 Parser fir WSDL Die Parser Erweiterung f r WSDL ist unter der geforderten Pr misse entwickelt worden dass die Quelldatei nur um die Dokumentation ver ndert wird D h dass der vorhandene Inhalt bestehen bleiben soll sodass der Programmcode nicht ver ndert wird Unterschiedliche Formatierungen z B Leerzeichen und Zeilenumbr che v
145. t hat erf llt keines der untersuchten Dokumentationssysteme das wichtigste Kriterium n mlich die Unterst tzung beim Dokumentieren durch die Vorgabe von nicht sichtbaren Vertragselementen einer Schnittstelle Andere Anforderungen werden nur teilweise erf llt Daher wird in diesem Kapitel das neue Dokumentationswerkzeug iDoclt entworfen Bei der Anforderungsanalyse wurde festgestellt dass der Ansatz der thematischen Raster unabh ngig von einer Programmier oder Beschreibungssprache ist Dies gilt ebenso f r den strukturellen Aufbau der Dokumentationsbl cke Daher soll das Werkzeug in fixe und variable Komponenten aufgeteilt werden die ber Schnittstellen miteinander kommunizieren siehe Abbildung 5 1 Eclipse Doclt Services Generische User Interface Core ee Grammatik Fixe Komponenten Variable Komponenten Parser Erweiterungen gt verwendet 3 enth lt Abbildung 5 1 Aufteilung in fixe und variable Komponenten von iDoclt im Kontext von Eclipse Die fixen Komponenten von iDoclt sind die grafische Oberfl che User Interface und die Plattform Core mit ihren Diensten die sie zur Verf gung stellt Die Parser Erweiterungen sind die variablen Komponenten Sie k nnen sich variabel an der Plattform an und abmelden Im Folgenden wird zun chst die generische Grammatik entwickelt die die meisten Schnittstellenstrukturen abb
146. t kann dabei aus keinem leeres Wort einem oder mehreren Terminalen aus dem definierten Alphabet X bestehen Die Menge aller W rter die aus 2 abgeleitet werden k nnen wird mit X bezeichnet Mit einer formalen Grammatik k nnen also W rter gebildet werden die zu einer bestimmten formalen Sprache geh ren aber es kann auch berpr ft werden ob ein Wort zu einer bestimmten Sprache geh rt Wortproblem 34 Vgl Socher Rolf Theoretische Grundlagen der Informatik 2008 Alphabet S 16f 35 Vgl Socher Rolf Theoretische Grundlagen der Informatik 2008 Grammatik S 65ff 38 5 1 Grammatiken Grammatik G N P S mit N A B x a b P A aA B B bB S AEN Tabelle 5 1 Beispiel einer Grammatik G Eine beispielhafte Grammatik G ist in Tabelle 5 1 definiert Die Nichtterminale werden hier als Gro buchstaben dargestellt und die Terminale als Kleinbuchstaben Der senkrechte Strich in der einen Produktionsregel bedeutet dass entweder das eine oder das andere Ergebnis aus der Produktion resultieren kann Dadurch k nnen mehrere Produktionsregeln zusammengefasst werden Bei der l ngeren Schreibweise werden die Regeln alle einzeln aufgef hrt 4A gt a4 B gt A aA AB Ausgehend vom Startsymbol A k nnen W rter produziert werden die mit einer beliebigen Anzahl a s anfangen auch die leere Menge also kein a ist erlaubt und mit mindestens einem bis beliebig vielen b s au
147. t ob der Dateityp unterst tzt wird Pr fung anhand der Dateiendung d h ob eine Parser Erweiterung f r diesen Typ verf gbar ist Sollte die Datei nicht unterst tzt werden wird dieses in der Oberfl che angezeigt siehe Abbildung D 5 Select Signature Element Document Signature Element No Signature Element selected artifact is not supported Overview of recommended roles for Abbildung D 5 iDoclt Editor mit nicht unterst tzter Datei ge ffnet Falls eine Parser Erweiterung f r diesen Typ vorhanden ist wird die Struktur der Schnittstelle angezeigt siehe Abbildung D 6 Die Dokumentationen k nnen dann f r die einzelnen Schnittstellenelemente erfasst werden In dem Baum Select Signature Element kann in der Schnittstellenstruktur navigiert werden Klicken Sie das Element an das Sie dokumentieren m chten Nach der Auswahl werden bereits gespeicherte Dokumentationen auf der rechten Seite in einer Liste von Dokumentationsbl cken gezeigt Mit dem Klick auf die Schaltfl che Add Thematic Role documentation kann ein Dokumentationsblock dem Signaturelement hinzuf gt werden Mit dem Klick auf die Schaltfl che X wird der entsprechende Dokumentationsblock wieder aus der Liste entfernt In einem Dokumentationsblock kann eine Thematic Role thematische Rolle und ein Scope Sichtbarkeitsbereich ausgew hlt werden sowie f r die hinterlegten Adressaten Beschre
148. teiressource und berf hrung in ein InterfaceArtifact write zum Zur ckschreiben eines InterfaceArtifacts in eine Dateiressource e isSupported zum Pr fen ob der bergeben Dateityp von dem Parser unterstiitzt wird e getSupportedType um den unterst tzten Dateityp abzufragen und e getDelimiters zum Abrufen der von dem Parser verwendeten Trennzeichen f r einen Elementpfad siehe Kapitel 5 3 S 58 de akra idocit extensions Parser O parse iFile IFile InterfaceArtifact O write interfaceStructure Interface rtifact iFile IFile void O isSupported type String boolean e getsupportedType String getDelimiters Delimiters Abbildung 5 10 Klassendiagramm des Interfaces Parser Jede Parser Extension Komponente muss das Parser Interface implementieren ParserImplementation um sich als Extension registrieren zu k nnen Eine Parser Erweiterung enth lt auch die erweiterte allgemeine Schnittstellenstruktur Extended Interface Artifact Structure also die von der Abstract Interface Artifact Structure erbenden Klassen Eine Parser Extension 55 5 2 Modularisierung und Erweiterbarkeit Komponente bildet immer einen eigenst ndigen Parser f r eine Programmier oder Beschreibungssprache Das Verhalten der Komponenten wird in Kapitel 5 5 n her beschrieben 5 3 Parser f r Schnittstellen In Kapitel 5 2 2 wurde bereits gezeigt dass es f r jede unterst tzte Programmi
149. tform enth lt die abstrakte allgemeine Schnittstellenstruktur und bietet Dienste zum Laden und Speichern eines Schnittstellenartefakts sowie einen Dienst zum Ableiten von thematischen Rastern aus einem Operationsbezeichner an In diesem Kapitel sollen einige Details zu dieser Struktur und der Plattform erl utert werden 6 1 1 Abstrakte Schnittstellenstruktur Wie bereits in Kapitel 5 1 2 erw hnt ist ein SignatureElement siehe Abbildung 5 5 S 47 nicht eindeutig durch seine Attribute identifizierbar weswegen ein technischer Schl ssel als das Attribut id eingef hrt wurde Ben tigt wird dieser eindeutige Schl ssel f r die Verwaltung von Informationen zu einzelnen SignatureElements au erhalb der Struktur des InterfaceArtifacts Beispielsweise werden in der grafischen Oberfl che von den Dokumentationsbl cken eines SignatureElements die zuletzt aktiven Adressatenreiter gespeichert Dadurch k nnen diese bei erneuter Auswahl des SignatureElements wieder vorausgew hlt werden Ohne den technischen Schl ssel k nnten die gespeicherten Daten f r ein SignatureElement nicht eindeutig wiedergefunden werden Ein Datentyp kann beispielsweise f r mehrere verschiedene Operationsparameter verwendet werden Aus den Attributen dieses Typs resultieren immer die gleichen 70 6 1 Plattform Core SignatureElements bzw Parameter Wenn man diese Objekte isoliert miteinander vergleicht sind sie identisch
150. tiert ist Wichtige Bestandteile des Schnittstellenvertrags bleiben so undokumentiert Zum Beispiel werden Seiteneffekte und verwendete Ressourcen die nicht als Parameter deklariert sind nicht ber cksichtigt Der Autor muss selbst die Operation nach Seiteneffekten und implizit verwendeten Ressourcen analysieren um sie dann zu dokumentieren Dieses birgt die Gefahr dass etwas bersehen wird und damit undokumentiert bleibt Diese Problematik l sst sich durch die Metaphern Stille und Rauschen charakterisieren e Stille Relevanter Aspekt der Operation welcher in der zugeh rigen Dokumentation nicht erw hnt wird e Rauschen Redundante bzw unn tig ausf hrliche Dokumentation zu einem Aspekt der Operation Wo Stille in der O Doku auftreten kann wurde gerade gezeigt Wie Rauschen auftreten kann wird an einem realen Beispiel aus der ffentlichen eBay Trading API N verdeutlicht In der eBay Trading API wird die Bewertung z B eines Benutzers eines Artikels oder einer Transaktion Feedback genannt ber die Operation GetFeedback kann die jeweilige Bewertung abgerufen werden Diese Operation wollen wir im Folgenden n her betrachten 8 Vgl Z llighoven Heinz Object Oriented Construction Handbook 2005 S 38ff 9 Vgl Meyer Bertrand Formalism in Specifications 1985 S 6 25 10 Vgl Krause Jan Christian Stille und Rauschen 2011 11 Vel 0 V eBay Trading API o J 12 2 Dokumentation von Operationen mit them
151. tion lt wsdl message name nmtoken gt lt wsdl documentation gt lt part name nmtoken element qname type qname gt lt wsdl message gt lt wsdl binding name nmtoken type qname gt lt wsdl documentation gt lt extensibility element gt lt wsdl operation name nmtoken gt lt wsdl documentation gt lt extensibility element gt lt wsdl input gt lt wsdl documentation gt lt extensibility element gt lt wsdl input gt lt wsdl output gt lt wsdl documentation gt lt extensibility element gt lt wsdl output gt lt wsdl fault name nmtoken gt lt wsdl documentation gt lt extensibility element gt lt wsdl fault gt lt wsdl operation gt lt wsdl binding gt lt wsdl service name nmtoken gt lt wsdl documentation gt lt wsdl port name nmtoken binding qname gt lt wsdl documentation gt lt extensibility element gt lt wsdl port gt lt extensibility element gt lt wsdl service gt lt extensibility element gt lt wsdl definitions gt Tabelle B 2 Fortsetzung WSDL 1 1 Spezifikation 127 C Java Interface Deklaration C Java Interface Deklaration In Tabelle C 1 ist die Spezifikation einer Java Interface Deklaration aus der Java Sprachspezifikation der 3 Edition
152. tung der Attribute wird dann am Verwendungsort die Operation dokumentiert Das hat zur Folge dass kontextabh ngige Fallunterscheidungen in der Verwendung des Attributs bei der direkten Dokumentation des inneren Attributs entfallen Ein Beispiel soll dieses Prinzip erl utern Dazu wird der Parameter DetailLevel der bereits bekannten Operation GetFeedback der eBay Trading API betrachtet Durch diesen Parameter kann der abgerufene Informationsumfang eingeschr nkt werden Die Werte die der Parameter annehmen kann sind in Tabelle Tabelle 3 2 aufgelistet Die Beschreibungen zu den Werten sind aus Platzgr nden nicht mit aufgef hrt Die Beschreibung zu dem Wert ReturnSummary ist im Folgenden exemplarisch aufgef hrt Returns the summary data For GetMyMessages this detail level returns the same data whether or not you include MessagelDs or AlertIDs in the request Returns up to 10 FolderID and FolderName values Currently this detail level is the only way to retrieve FolderID and FolderName values See GetMyMessages in the eBay Web Services Guide for a code sample that demonstrates this 2 29 Vel 0 V eBay Trading API DetailLevelCodeType o J 25 3 3 Dokumentationswerkzeug DetailLevelCodeType ItemReturnAttributes ItemReturnCategories ItemReturnDescription ReturnAll ReturnHeaders ReturnMessages ReturnSummary Enumerationswerte Tabelle 3 2 Enume
153. un sisi do 45 Tabelle 5 4 Inhalt der plugin xml f r die WSDL Parser Erweiterung 57 Tabelle 5 5 Pfad von der WSDL Message GetFeedbackRequest der Operation GetFeedback aus der eBay Trading API bis zum Attribut UserID vom Typ USED IP Een eek es 60 Tabelle 6 1 Auszug der Klasse Parametern unseren 74 Tabelle 6 2 Auszug der Klasse SignatureElement enseenennennnenen 74 Tabelle 6 3 Auszug der Klasse WSDLMessage uucssesssesssensnnenensnnnnnnnnnen nenn 75 Tabelle 6 4 lt documentation gt Elementstruktur f r Dokumentation von thematischen Rollen und verschiedenen Adressaten cccescesesseeteeeeeeeeceeenseeaeeeees 79 Tabelle 6 5 Auszug von WSDL Elementen mit den von WSDL4J unterst tzten A A O A 81 Tabelle 6 6 Auszug aus WSDL 1 1 SpezifikatiOD oooonocnnnnnnnnonoccnnocnononconncconanccnnnns 82 Tabelle 6 7 Zuordnung der iDoclt Dokumentationsbl cke in die WSDL der eBay nD ACTA OAR ee 86 Tabelle 6 8 Auszug der Java Sprachspezifikation fiir eine Interface Deklaration in EBN ES to 92 Tabelle 6 9 Auszug der m glichen Modifier der Java Sprachspezifikation in EBNF a ai 93 Tabelle 6 10 Beispiel einer Java Klasse zur Erl uterung der JavaBeans Spezifikation diia 93 Tabelle 6 11 Auszug der Methode aus der Klasse DocumentltemListComposite zum Hinzuf gen einer Documentation DocumentltemComposite 101 5 Tabelle 6 12 Auszug der Methode aus der Klasse DocumentItemListC
154. ungen die ein Dokumentationswerkzeug und ein Format erf llen m ssen In diesem Kapitel wird ermittelt welche allgemeinen Basisanforderungen Schnittstellen dokumentationen und welche softwaretechnischen Anforderungen ein Werkzeug erf llen soll Die Formate von Dokumentationen verwenden zur Strukturierung Auszeichnungs sprachen Markup Language bzw Beschreibungssprachen Descriptive Markup Language Durch den strukturierten Aufbau k nnen diese einfacher programmatisch ausgewertet werden Eine Beschreibungssprache besitzt eine Syntax durch die Informationen beschrieben werden k nnen Es existieren also Auszeichnungen Markups die einen logischen Zusammenhang zwischen einer Auszeichnung und einem Text herstellen In den Schnittstellendokumentationen werden z B Schl sselw rter oder XML Syntax als Auszeichnung und Strukturierung der Texte verwendet Die Schl sselw rter k nnen verschiedene Auspr gungen haben Bei Javadoc z B durch W rter die mit einem Zeichen beginnen z B param um den logischen Zusammenhang zu einer Parameterbeschreibung herzustellen und nach dem Schl sselwort folgt der dazugeh rige Text In XML wird ein Text nicht nur durch ein Schl sselwort eingeleitet sondern durch einen Anfang und ein Ende umschlossen z B lt Schl sselwort gt Text lt Schl sselwort gt In dem Kontext dieser Bachelorarbeit werden nur Dokumentationswerkzeuge behandelt die bei der Erstellung und Bearbeitung von O Doku bzw
155. werden um dessen Elemente zu parsen Es existieren f r Java viele solcher Parser die eine XML Struktur parsen k nnen wie z B der Xerces2 Java Parser oder der DocumentBuilder und SAXParser aus dem javax xml parsers Paket der Java Platform Standard Edition 6 Es existieren auch Parser die eine WSDL parsen und eine Java Objektstruktur als Ergebnis ausgeben Beispiele daf r sind WSDLAJ und das Membrane SOA Model Der DocumentBuilder und SAXParser sind reine XML Parser und k nnen die geparste Struktur nicht wieder zur ckschreiben Der Xerces2 Java Parser bietet dagegen mit dem LSSerializer aus dem Paket org w3c dom 1s die M glichkeit ein DOM Document Object Model Dokument auch zu schreiben Aber beim Parsen m ssen per Hand die eingelesenen Elemente in eine Objektstruktur berf hrt werden nderungen m ssen dann wieder in das DOM Dokument eingepflegt werden damit sie gespeichert werden k nnen WSDL4J und das Membrane SOA Model bieten direkte Unterst tzung der WSDL an Sie parsen eine WSDL Datei und erstellen daraus eine Java Objektstruktur Diese Objektstruktur kann dann manipuliert und wieder gespeichert werden Das Membrane SOA Model ist zwar kostenlos nutzbar aber deren API ist nicht dokumentiert und deren Quellen auch nicht ffentlich zug nglich WSDL4J ist quelloffen und auch dokumentiert weswegen die Entscheidung letztendlich auf WSDL4J gefallen ist 48 Vel 0 V Xerces2 Java Parser o J
156. wird Eine WSDLMessage entspricht einem WSDL lt message gt Element sie hat aber eine Referenz auf ein Input Output oder Fault Objekt einer Operation der WSDLAJ Objektstruktur Das hat sie deswegen weil ein lt message gt Element i d R au erhalb des lt portType gt Elements definiert ist Daher soll die Dokumentation der WSDLMessage und deren WSDLParameter nicht in das lt message gt Element geschrieben werden sondern in das entsprechende lt input gt lt output gt oder lt fault gt Element Au erdem kann dasselbe lt message gt Element in verschiedenen Operationen und somit auch in unterschiedlichen Kontexten verwendet werden Die spezifischen Dokumentationen werden dann nach dem Lokalit tsprinzip zur Operation geschrieben Die WSDLOperation h lt eine Referenz auf das jeweilige 83 DLParameter ben tigt kein zus tzliches Attribut weil deren 6 2 Parser fiir WSDL Operation Objekt aus der WSDL4J Objektstruktur Das Attribut portType der Klasse WSDLInterface referenziert ein PortType Objekt und aus der Klasse WSDLInterfaceArtifact wird das Definition Objekt referenziert Fiir die Elemente lt definitions gt lt portType gt und lt operation gt wird die Dokumentation in das jeweilige enthaltene lt documentation gt Element geschrieben F r die lt input gt lt output gt und lt fault gt Elemente kann keine direkte Dokumentation erfasst werden sondern f r die enthaltenen lt message gt E
157. zer anfangen die einzelnen Signaturelemente der Schnittstelle zu dokumentieren Beim Klick auf eines der Signaturelemente in dem Elementbaum SelectSignatureElementComposite wird das Element erst einmal berpr ft ob es ein Element einer Operation ist oder nicht siehe Abbildung 5 19 Zu den Elementen einer Operation z hlen die Operation selbst Eingaben Ausgaben Ausnahmen und die Attribute der Typen der Eingaben Ausgaben und Ausnahmen Wenn es eines dieser Elemente ist wird der Operationsbezeichner an die Core Komponente ThematicGridService weitergegeben Dort werden die thematischen Raster f r das im Bezeichner enthaltene Verb abgeleitet F r jede thematische Rolle in den Rastern wird gepr ft ob diese bereits innerhalb der Operationselemente oder in einem seiner Elternelemente zugeordnet worden sind 68 5 5 Kommunikation der Plattform Services Wenn es wenigstens einmal zugeordnet worden ist erh lt es eine Kennzeichnung in der Oberflache Dann werden die thematischen Raster in der Oberflache angezeigt im DisplayRecommendedRolesComposite Wenn das selektierte Signaturelement bereits dokumentiert wurde werden die Dokumentationsbl cke in der Komponente DocumentationItemListComposite aufgelistet Wenn die nderungen im iDoclt UI gespeichert werden sollen kann der Benutzer auf die Speichern Schaltfl che von Eclipse klicken Das Sequenzdiagramm in Abbildung 5 20 beschreibt den internen Ablauf von iDoclt zum Spe
158. zifikation 41 Vgl Chinnici Roberto et al WSDL Version 2 0 2007 40 5 1 Grammatiken lt wsdl portType name nmtoken gt lt wsdl operation name nmtoken gt lt wsdl input name nmtoken message qname gt lt wsdl output name nmtoken message gname gt lt wsdl fault name nmtoken message qname gt lt wsdl operation gt lt wsdl portType gt Tabelle 5 2 Auszug der WSDL 1 1 Spezifikation f r das lt portType gt Element In Java besteht eine Operation aus beliebig vielen Eingabeparametern einem Ergebnistypen und einer Menge m glicherweise auftretender Ausnahmen In der WSDL ist es ein wenig komplizierter Eine Operation hat ein oder kein lt input gt und lt output gt Element f r die Eingaben und Ausgaben sowie eine beliebige Menge von lt fault gt Elementen f r eventuelle Ausnahmen siehe Tabelle 5 2 Jedes dieser Elemente referenziert ein lt message gt Element Meist wird f r jede Operation ein Input Message Typ und ein Output Message Typ definiert Es ist aber auch m glich dass sich mehrere Operationen einen Message Typ teilen Ein lt message gt Element besteht aus beliebig vielen lt part gt Elementen die entweder ein Element referenzieren oder einen komplexen oder einfachen primitiven Typen haben z B ein Ganzzahltyp siehe Abbildung 5 2 42 Legende 0 bis 1 Mal vorhanden 0 bis beliebig oft vorhanden 43 Vgl Anhang B 44 Vgl T
159. zu ist die Erstellung einer tiefen Kopie eines SignatureElements das in Kapitel 6 1 1 beschrieben wird 47 5 1 Grammatiken Der Entwickler ist auch daf r verantwortlich alle n tigen Informationen in den jeweiligen Objekten zu speichern sodass die Struktur nach dem Erstellen und Manipulieren auch wieder in die Datei bzw Quelle zur ckgeschrieben werden kann Um das zu erreichen m ssen die einzelnen Klassen der allgemeinen Schnittstellenstruktur beerbt werden F r die Parser Erweiterungen f r WSDL und Java ist dieses in Kapitel 6 2 3 und 6 3 3 gezeigt 5 2 Modularisierung und Erweiterbarkeit Wie in Kapitel 3 4 beschrieben wird bei der AKRA GmbH haupts chlich die Entwicklungsumgebung Eclipse eingesetzt in die das Werkzeug iDoclt integriert werden soll Zur Modularisierung sollen daher die Komponenten UI Core und die Parser Erweiterungen siehe Abbildung 5 1 jeweils als ein Eclipse Plugin realisiert werden Durch die Modularisierung soll die Funktionalit t von iDoclt auf einzelne Komponenten aufgeteilt werden Die Komponenten sollen ber definierte Schnittstellen miteinander kommunizieren Die Ul Komponente greift dabei auf die Core Komponente zu aber nicht umgekehrt Die Core Komponente und die Parser Erweiterungen z B die f r Java und WSDL verwenden sich gegenseitig Diese strikte Kapselung von Funktionalit t soll die Wartbarkeit erh hen und die sp teren Weiterentwicklungen f rdern Realisiert werden soll

Bachelorarbeit von Dirk Meier-Eickhoff

Contents

Download Pdf Manuals

Related Search

Related Contents