Inhalt
ERROR: not found ---/root//topics:topic[@ident='XmlDocuGen']/topics:topic[@ident='StateOfCompletion']/topics:topic[@ident='todoXsl']---
Topic=.UmlDocu.UmlInDocument.
UML, die Unified Modelling Language der Objektorientierten Programmierung ist in gewisser Hinsicht Dokumentation selbst und bedarf keiner weiteren Aufbereitung. Das ist durchaus ein Standpunkt. Vorausgesetzt wird dabei, dass ein Tool für UML in Zugriff ist, mit dem Tool kann man im Modell navigieren. UML lebt von Diagrammen. Aus den Diagrammen können Modellelemente selektiert werden um ihre Details anzusehen. Aus Diagrammen oder aus den Modellelementen und dem zugehörigen Browserbaum kann man in andere Diagramme navigieren.
In diesem Sinn ist eine Dokumentengenerierung aus UML oft nur ein Festfrieren des Modellinhaltes (er kann nicht mehr geändert werden) um daraus ein Abbild in Standard-Dokumentationsmedien zu erzeugen. Damit ist dieser UML-Entwurf auch ohne das UML-Tool anschaubar. Eine Selektion bestimmter Teile für die Dokumentengenerierung wird unterstützt. UML-Tools können teils auch fremde Dokumente einziehen. Dann kann man auch UML-fremde Anteile in die aus UML generierten Dokumente einfließen lassen. Standard-Dokumentationsmedien sind HTML für Browseransicht, PDF, Winword. Bei Sicht auf die Dokumentengenerierung aus UML steht das UML-Modell im Mittelpunkt. Fremdanteile für die Dokumentation müssen im UML-Modell vorhanden sein, um in der erzeugten Dokumentation zu erscheinen.
Die hier vorgestellt Dokumentengenerierung rückt das UML-Modell aus dem Mittelpunkt heraus auf die Seite. Teile aus dem UML-Modell werden für die Dokumentation genutzt. Die Dokumentation kann aber auch noch aus anderen Teilen bestehen, vollständig außerhalb des UML-Modells. Das ist in erster Linie damit begründet, dass die XML-Dokumentengenerierung nicht zum Zwecke der UML-Dokumentation entstanden ist sondern von einem allgemeinerem Ansatz her.
In zweiter Linie muss allerdings auch festgestellt werden, dass UML auch nur ein Mittel zum Zweck ist. UML-Toolhersteller reden gern von Modellgetriebener Entwicklung. Alles aus einer Hand ist ein Slogan, der eher vom Verkaufsinteresse geprägt ist. In diesem Sinn liefern Tools oft alles, was man braucht. Bezüglich Softwareentwicklung umfasst dies die Versionspflege der Softwarequellen, die Anforderungs- und Änderungsverfolgung, Testunterstützung und so weiter. Doch ein Blick in die Praxis zeigt, dass diese vielfältiger ist. Sei es, dass die Orientierung auf genau einen Tool-Hersteller gar nicht erwünscht ist um eine Flexibilität zu erhalten, oder dass es Vorbedingungen oder weitere Anforderungen gibt, die nicht auf den Tool-Hersteller für UML passen. Der Slogan Alles aus einer Hand kann auch ersetzt werden von der Anforderung, Standards zu benutzen und austauschbar zu sein.
Die Einbindung von UML-Entwürfen in die Dokumentation basiert auf dem standardisierten XMI-Export des UML-Modells. Der XMI-Export ist für UML2.0 von der omg.org, der Organisation zur Pflicht erklärt. UML-Tools müssen diesen Standard unterstützen, damit die Modelle über Toolgrenzen hinaus austauschbar sind.
Topic=.UmlDocu.General_SelectFromUml.
Welche Anteile aus einem UML-Modell können in eine XML-generierte Dokumentation einfließen: Zunächst kann eine Unterteilung in zwei Gruppen erfolgen:
Diagramme
Internas von Modellelementen
Grundsätzlich erfolgt die Auswahl einzeln im Steuerfile der Dokumentengenerierung. Damit liegt die Feingestaltung der Dokumentation in der Hand des Anwenders. Allerdings kann ein ausgewähltes Element, beispielsweise ein Package, auch eine sehr umfangreiche Dokumentation seines Inhaltes selbst erzeugen. Wichtig ist hierbei die Einflußnahme auf die Ausgabe über Parametrierung.
Topic=.UmlDocu.General_SelectFromUml..
Diagramme stellen Strukturen dar. Sie brauchen eine Erläuterung. XMI sieht vor, dass jedes Modellelement, auch jedes Diagramm eine Beschreibung haben kann. Im XMI-Format wird das als <UML:TaggedValue tag="documentation" value="..." /> gespeichert. Es ist ein guter Stil, in die Beschreibung zu einem Diagramm einen nicht zu knappen Text hineinzupacken, der die Motivation des Diagramms erläutert und durch die wichtigsten Teile führt. Der Umfang solle in etwa auf eine Druckseite A4 passen, wenn gemeinsam mit dem Diagramm selbst, dann ist das natürlich günstig.
Damit kann aus Diagrammen mit ihrer Erläuterung bereits eine gehaltvolle Dokumentation zusammengebaut werden. Kennzeichen der XML-Dokumentengenerierung ist, dass die Gliederung der Dokumentation, die Kapitelstruktur, und die Inhaltsauswahl in einem Steuerfile der Dokumentengenerierung festgelegt wird. Damit wird dort bestimmt, wo welches Diagramm erscheinen soll und welcher Text erscheinen soll.
Topic=.UmlDocu.General_SelectFromUml..
Die Beschreibung von Schnittstellen ist ein wesentlicher Bestandteil von Dokumentationen. Schnittstellen können statisch beschrieben werden, mit Benennung der ausgetauschten Daten (Format, Bedeutung), der dynamische Anteil von Schnittstellen-Festlegungen wird aber oft unterschätzt:
Wann werden Daten ausgetauscht, zeitlicher Ablauf,
Welcher Kontext gilt.
Für die Dynamik können wiederum UML-Diagramme benutzt werden: Sequenzdiagramme für Abläufe, Zustandsdiagramme für eine exakte Kontextdarstellung, Use-Case-Diagramme für eine Übersicht.
Für den statischen Anteil kann allerdings der Inhalt der Schnittstellenklassen herangezogen werden, mit Benennung aller Methoden und deren Argumente mit zugehöriger Beschreibung.
Topic=.UmlDocu.General_SelectFromUml..
Zustandsdiagramme (Statechart, Statediagramm) sind nur die bildliche Darstellung von Zustandsabläufen, dahinter verbergen sich Modellelemente: State und Transition. Es ist nun durchaus informatorisch, eine ausführlichere Beschreibung der Bedeutung jedes Zustandes zu haben. Das kann als Beschreibung am Modellelement State im UML-Modell notiert werden, unabhängig vom Statediagramm selbst.
Interessant ist dann eine Auflistung, welche Übergänge von einem Zustand aus möglich sind, mit Nennung ihrer genauen Bedingungen und Aktionen und einer Beschreibung. Das ist ergänzend zum Statediagramm selbst. Dort sind die Zustandsübergänge zwar sichtbar, aber Detailbeschreibungen sind viel zu umfangreich für das Bild selbst.
Topic=.UmlDocu.General_SelectFromUml..
In einem Objektmodelldiagramm sind zwar alle Klassen eines Packages zeigbar, aber Objektmodelldiagramme haben meist nicht die Aufgabe, die statische Klassenstruktur zu zeigen, sondern sollen den Zusammenhang bestimmter Klassen ggf. über Packagegrenzen hinweg für eine Problemstellung erläutern. Die statische Struktur lässt sich dagegen besser textuell als Liste darstellen. Dabei kann die Beschreibung jeder Klasse mit oder ohne Details dargestellt werden.
Topic=.UmlDocu.SelectFromUml.
Im Steuerfile der Dokumentengenerierung kann wie in folgenden Beispielen innerhalb eines Dokumentes oder Kapitels notiert werden:
Inhalt des Packages wird dargestellt: Die Packagebeschreibung wird ausgegeben.
Alle Klassen mit ihrer Klassenbeschreibung werden aufgezählt. Klasseninhalte werden nicht dargestellt. Hinter dem Steuerwort class kann alles angegeben werden, was auch bei umlClass(... class=) angegben werden kann. Außerdem sind auch wie bei umlClass die Steuerworte method=, attribute=, association=, wie bei umlClass() wirksam.
Der Inhalt der Klasse wird dargestellt. Ohne weitere Angaben wird dabei nur die Klasse benannt und ihre Description ausgegeben.
Der Inhalt einer Klasse wird dargestellt. Für die gezeigten Kategorien class, methods, attributes usw. kann jeweils festgelegt werden, ob nur public-Elemente, protected und public-Elemente, private bis public-Elemente oder alle Elemente dargestellt werden sollen.
Der Unterschiede private und all ist folgender: Elemente können verborgen werden, in dem in ihrer Description am Anfang die Zeichenfolge HIDE### notiert wird. Solche Elemente werden auch bei private-Auswahl nicht ausgegeben, wohl aber bei all. Damit hat der Anwender beispielsweise die Möglichkeit, Elemente, die noch nicht für die Dokumentation freigegeben sind oder niemals dort dargestellt werden sollen, zu verbergen. Beipspielsweise kann das für interne Testelemente genutzt werden, die zwar im Quellcode sichtbar sind und benutzt werden sollen, in der Dokumentation aber nicht erscheinen sollen.
Der Inhalt des Comments wird ausgegeben. Im XMI ist dieser unter <UML:TaggedValue tag="documentation" value="..." /> gespeichert.
umlOMD(**/Diagram);
Die Beschreibung zu einem Object Model Diagram (KLassendiagramm) wird ausgegeben. Im XMI ist dieser unter <UML: tag="documentation" value="..." /> gespeichert. Das Diagramm selbst ist zwar im XMI enthalten, jedoch kann es auch aus der Darstellung des jeweiligen UML-Tools heraus als Bild gespeichert werden. Entweder man verwendet dazu einen einfachen Bildschirmabzug, wie er beispielsweise mit dem http://www.hardcopy.de möglich ist, oder das jeweilige Tool unterstützt einen Bilderexport. Im XMI ist weniger Information über das Aussehen des Diagramms gespeichert als für eine gute Darstellung notwendig ist. Die Beschreibung zur jeweiligen Diagrammart am Diagramm abgelegt wird mit dieser Steueranweisung ausgegeben.
umlSQD(**/Diagram); Die Beschreibung zu einem SequenceDiagramm wird ausgegeben. Im XMI ist dieser unter <UML:Collaboration tag="documentation" value="..." /> gespeichert. Bezüglich der Grafik selbst gilt die gleiche Aussage wie zum Klassendiagramm.