Dokumentieren von Quelltexten mit IsomlDoc

Excellence in Automotive Computing.

Bedienungsanleitung

Titel des Dokuments

Dokumentieren von Quelltexten mit IsomlDoc

Informationstechnik München

im Folgenden als

Dokument bezeichnet

Kurztitel

Bedienungsanleitung IsomlDoc

Vorgang

BZ-11586 externe Referenz

-

Das folgende Dokument ist geistiges und urheberrechtliches Eigentum der

Name und Anschrift

IFS Informationstechnik München

Trausnitzstraße 8

81671 München

im Folgenden als

IFS bezeichnet

Die IFS behält sich ausnahmslos alle urheberrechtlichen Ansprüche vor, welche sie gemäß der geltenden Rechtslage in der Bundesrepublik Deutschland sowie aus den jeweiligen Teilen des Werkes, für die die IFS aufgrund von erfinderischer Tätigkeit natürlicherweise die Urheberschaft besitzt, ableiten kann.

Unbeeinflusst davon sind Rechte Dritter, für die die IFS, gemäß den mit diesen Dritten vereinbarten Verträgen und Überlassungen, das vorliegende Werk ggf. auch im

Auftrag erstellt hat. Eine Abtretung der Urheberschaft kann daraus dennoch nicht abgeleitet werden.

Name

Sarah Erdmann

Datum

15. September 2010

Datum

22. Januar 2013

Nummer

2.0

Autorin des Dokuments

Erstellungsdatum

Datum der letzten Änderung

Version des Dokuments erfinden verbessern gewinnen • gemeinsam.

IFS Informationstechnik GmbH Trausnitzstraße 8 81671 München

Telefon +49 89 450983 0 Fax +49 89 450983 10 www.ifs-it.de

Kreissparkasse München Konto 10 110 344 BLZ 702 501 50

Amtsgericht München HRB 126547 USt-IdNr: DE203067267

Geschäftsführer: Dr.-Ing. Markus A. Stulle Dipl.-Ing. Thomas Frey



Dokumentinformationen

Status der vorliegenden Version

Bezeichnung freigegeben

Dieses Dokument unterliegt keinem systematischen Änderungsdienst.

Beteiligte und Rollen

Vorname Nachname

Dr.-Ing. Markus A. Stulle

Carsten Smekal

Roland Ott

Dr. Tim-Oliver Paaschen

Bettina von Staden

Rolle

Auftraggeber

Vorhabensverantwortlicher

Qualitätsbeauftragter

Gutachter

Lektorin

Speicherort des Dokuments

Pfad

\\ifshome.muc.smarttrust.de\IFS\Produkte\Taurus\02 Arbeitspakete\BZ-11586

(Bedienungsanleitung isomldoc)\06 Spezifikation\BZ-11586 Dokumentieren von

Quelltexten mit IsomlDoc v2.0.doc

2 von 28

Dokumentinformationen

Vorgang: BZ-11586

Kurztitel: Bedienungsanleitung IsomlDoc

Version: 2.0, 22. Januar 2013



Inhalt

Dokumentinformationen

1 Einleitung

2 Dokumentationsanweisungen für IsomlDoc

2.1

Allgemeine Hinweise

2.2

Grundlegende Dokumentationsanweisungen

2.3

Dokumentationsanweisungen für Funktionen

2.4

Weitere Dokumentationsanweisungen

3 Anwenden von IsomlDoc

3.1

Schritt 1: Werkzeug vorbereiten

3.2

Schritt 2: Quelltexte bereitstellen

3.3

Schritt 3: Konfiguration und Aufruf des Werkzeugs

3.4

Schritt 4: Erstellen der kompilierten Hilfe

B

Verzeichnisse und Anhänge

A Referenzen

Übersicht aller Dokumentationsanweisungen

9

12

12

13

6

8

5

5

18

22

23

23

23

2

4

3 von 28

Inhalt

Vorgang: BZ-11586




1


Einleitung

IsomlDoc ist ein Software-Dokumentationswerkzeug für ISOM/L-

Programme [1] . ISOM/L-Programme beschreiben die Details der

Software-Reparatur von Fahrzeugen. Mit IsomlDoc können aus

ISOM/L-Programmen automatisch HTML-Dokumente erzeugt werden, die das in den Programmen enthaltene Wissen über die Fahrzeugtherapie verfügbar machen. Dazu werden spezielle Dokumenta-

tionsanweisungen in den Quelltext eines ISOM/L-Programms eingefügt, die Erläuterungen zu bestimmten Programmelementen

(Namensräume, Annotationen, Funktionen) definieren. IsomlDoc erstellt daraus ein übersichtliches HTML-Dokument, das einen

Überblick über die Elemente des ISOM/L-Programms und die Einzelheiten der Fahrzeugtherapie bietet.

Gegenwärtig wird mithilfe von IsomlDoc aus der ISOM/L-

Bibliothek für Serviceautoren (IBS) eine kompilierte HTML-

Hilfedatei generiert. Diese beschreibt alle prominenten Namensräume und Fachfunktionen der IBS.

4 von 28

1 Einleitung

Vorgang: BZ-11586





2 Dokumentationsanweisungen für IsomlDoc

Das Werkzeug IsomlDoc verarbeitet die Quelltexte von ISOM/L-

Programmen. Damit aus den Quelltexten ein Dokument erstellt werden kann, müssen diese dafür vorbereitet werden: Die Funktionen und Namensräume in den Quelltexten müssen spezielle Dokumentationsanweisungen enthalten und mit Kommentaren erläutert werden. In diesem Kapitel werden die Dokumentationsanweisungen für IsomlDoc beschrieben. Eine Übersicht aller Dokumentations-

anweisungen bietet Anhang B.

Allgemeine Hinweise 2.1

IsomlDoc prüft zuerst, ob ein Kommentar relevant für die Dokumentation ist. Verarbeitet werden Blockkommentare, die mit /** oder /*! eingeleitet werden, und Zeilenkommentare, die mit /// oder //! beginnen.

Ein Kommentar wird im Normalfall dem nächsten folgenden ISOM/L-

Element (Namensraum oder Funktion) zugeordnet. Annotationen dürfen zwischen dem Kommentar und dem ISOM/L-Element stehen:

Quellcodeauszug

/**

* @brief Kurzbeschreibung des Namensraums Example.Template

* ...

*/

[Version(ver_major="6", ver_minor="0", ver_submaj="0", ver_submin="0")]

namespace Example.Template

{

// ...

}

Codeauszug: Kommentare

Kommentare im Rumpf von Funktionen werden von IsomlDoc nicht verwendet.

Quellcodeauszug namespace Example.Template

{

Example.Template Create(Isom.Base.String input)

{

//! Dieser Dokumentations-Kommentar wird ignoriert

}

}

Codeauszug: Kommentar im Rumpf einer Funktion

5 von 28

2 Dokumentationsanweisungen für IsomlDoc

Vorgang: BZ-11586





Alle Namensräume und Funktionen von ISOM/L-Programmen sollten dokumentiert sein. Undokumentierte Elemente werden von IsomlDoc bei der Dokumentationserstellung über die Taurus® Ereignisauf-

zeichnung protokolliert (siehe Kap. 3.3.2).

2.2 Grundlegende Dokumentationsanweisungen

Üblicherweise beginnt die Dokumentation mit einer Kurzbeschreibung, die nicht länger als ein Satz sein sollte. Darauf folgt eine detaillierte Beschreibung, die mehrere Abschnitte umfassen kann:

Quellcodeauszug

/**

* @brief Kurzbeschreibung des Namensraums

*

* @details

* Die vollständige Beschreibung des Namensraums soll sich auf invariante

* Teile beschränken. Weitergehende Details sind im Nachschlagewerk zu

* dokumentieren.

*/

Codeauszug: Dokumentationsanweisung Kurzbeschreibung

Längere Detailbeschreibungen können in Absätze und Kapitel untergliedert werden. Einfache Absätze trennt man durch eine

Leerzeile im Kommentar. Für benannte Absätze und Kapitel stehen

Dokumentationsanweisungen zur Verfügung:

6 von 28


Vorgang: BZ-11586





Quellcodeauszug

/*

* @details

* Ausführliche Beschreibung ...

*

* Ein neuer Absatz beginnt nach einer Leerzeile.

*

* @par Überschrift des benannten Absatz

* Ein solcher Absatz wird eingerückt dargestellt

* und endet an der nächste Leerzeile.

*

* @section Kapitel_1 Titel des Abschnitts

* Die erste Zeichenkette ist der Name des Kapitels.

* Der Name wird nicht in der erzeugten Dokumentation angezeigt!

*

* @subsection Unterabschnitt1 Überschrift

* Ein Unterkapitel

*

* @subsubsection Unterunterabschnitt1 Überschrift

* und ein Unterkapitel der zweiten Ebene

*/

Codeauszug: Dokumentationsanweisungen für Kurzbeschreibungen

Auf benannte Kapitel kann man verweisen:

Quellcodeauszug

*

* @ref Kapitel_1

* Als Text für diesen Verweis wird der Titel des Kapitels verwendet.

*

* @ref Kapitel_1 "Alternative Bezeichnung"

* Als Text für diesen Verweis wird der Titel des Kapitels ignoriert und

* die Bezeichnung in Anführungszeichen verwendet.

*

Codeauszug: Auf benannte Kapitel verweisen

Will man nicht auf ein Kapitel, sondern ein anderen Teil des

Textes verweisen, so kann man dort eine Zielmarke anlegen:

Quellcodeauszug

* @anchor Dtc_Beispiele

Codeauszug: Zielmarke

7 von 28


Vorgang: BZ-11586




2.3


Dokumentationsanweisungen für Funktionen

Bei der Beschreibung einer Funktion ist darauf zu achten, dass der Rückgabewert und alle Parameter beschrieben werden:

Quellcodeauszug

/**

* @brief Kurzbeschreibung der Funktion

*

* @details

* Die vollständige Beschreibung der Funktion

*

* @param input Eingabeparameter

* @return Rückgabewert

*/

Template Create(Isom.Base.String input);

Codeauszug: Beschreibung einer Funktion

Auch Fehlerfälle sowie Vorbedingungen, Nachbedingungen und wichtige Invarianten sollten mit den entsprechenden Dokumentationsanweisungen beschrieben werden:

Quellcodeauszug

*

* @exception Das Void-Objekt wird zurückgegeben, falls ... ein Fehler

* auftritt.

*

* @pre Eine Vorbedingung könnte sein, dass der Soll-Kontext bekannt

* sein muss

* @post Eine Nachbedingung könnte sein, dass der Plan alle erforderlichen

* Logistikdaten enthält

* @invariant Eine Invariante könnte sein, dass die Liste der Steuergeräte

* nicht verändert wird

*

Codeauszug: Fehlerfälle, Vor- und Nachbedingungen, Invarianten

In der Regel sollte zu jeder Funktion ein Quelltext-Beispiel angegeben werden. Dabei ist darauf zu achten, dass dieses

Beispiel mit „Kopieren und Einfügen“ übernommen werden kann:

8 von 28


Vorgang: BZ-11586





Quellcodeauszug

*

* @code

* // Steuergerät mit Diagnoseadresse 16 ermitteln

* Isom.Context.FutureVehicleContext

* fvc = Isom.Context.FutureVehicleContext.GetInstance();

* Isom.Context.EcuList fvcEcus = fvc.GetEcus();

* Isom.Context.Ecu ecu = fvcEcus.FindByEcuAddress( "16" );

*

* if(ecu.IsVoid().Not())

* {

* // Programmierung hinzufügen

* Isom.Plan.TherapyPlan tp = Isom.Plan.TherapyPlan.GetInstance();

* Isom.Plan.TherapyPlanAction tpa

* = tp.CreateEcuAction( "Flash", ecu );

* if(tp.Add( tpa ).Failed())

* {

* // Fehlerbehandlung

* }

* }

* @endcode

*

Codeauszug: Quelltextbeispiel

2.4 Weitere Dokumentationsanweisungen

In den Detailbeschreibungen können weitere Dokumentationsanweisungen verwendet werden, die besondere Unterkapitel einleiten:

Quellcodeauszug

*

* @remarks

* Anmerkungen

*

* @note

* Hinweis

*

* @attention

* Achtung

*

* @warning

* Warnung

*

* @see

* Verweis auf andere relevante Kapitel

*

Codeauszug: Einleitungen für Unterkapitel

9 von 28


Vorgang: BZ-11586





In der Regel werden auch Autor, Gutachter und das Datum der letzten Bearbeitung dokumentiert:

Quellcodeauszug

* @author XY (Autor)

* @author ZZ (Gutachter)

* @date letzte Änderung am 23.09.2010

Codeauszug: Autor, Gutachter und Datum

Außerdem kann für eine Funktion angegeben werden, seit wann sie angeboten wird, oder ob sie nicht mehr verwendet werden sollte:

Quellcodeauszug

*

* @since Eingeführt zu Version 3.0.0.0

*

* @deprecated Wird seit Version 5.3.0.0 nur noch aus Kompatibilitäts-

* gründen unterstützt.

*

Codeauszug: Weitere Details für Funktionen

Aufzählungspunkte leitet man durch ein Minuszeichen ein. Um die

Punkte zu nummerieren, verwendet man zusätzlich eine Raute

(-#). Unterschiedliche Einrückungstiefen erzeugen verschachtelte Aufzählungen:

Quellcodeauszug

*

* Punkt 1

* Punkt 1.1

* Punkt 1.1.1

* Punkt 1.1.2

* Punkt 1.2

* Punkt 1.3

* Punkt 2

*

* -# Nummerierung 1

* -# Nummerierung 2

* -# Nummerierung 3

*

Codeauszug: Aufzählung und Nummerierung

In Namensräumen mit zahlreichen Funktionen bietet es sich an,

Gruppierungen vorzunehmen. Eine Gruppe fasst eine Reihe von

Funktionen zusammen. Diese Funktionen werden in der Übersicht

(am Anfang des Namensraums) zusammen dargestellt. Mit der Anweisung @name wird eine Überschrift und eine Beschreibung der

Gruppe angegeben. Die beiden Anweisungen @{ und @} markieren dann Beginn und Ende der Gruppe.

10 von 28


Vorgang: BZ-11586





Quellcodeauszug

/** @name Elementmethoden aller ISOM/L-Objekte

* Technische Methoden, die von allen Fach- und Basisobjekten unterstützt

* werden.

* @{

*/

/**

* Bestimmt, ob es sich um das Void-Objekt handelt.

*

* @return 'true', falls dies das Void-Objekt ist, 'false' sonst.

*/ objectbound Boolean IsVoid();

/**

* Erzeugt eine identische Kopie des Objekts.

*

* @return Das geklonte Objekt.

*/ objectbound DtcList Clone();

/**

* Erzeugt ein ungültiges Objekt.

*

* @return Ungültiges Objekt.

*/

DtcList Void();

/** @} */

Codeauszug: Funktionen gruppieren

11 von 28


Vorgang: BZ-11586




3

3.1


Anwenden von IsomlDoc





Die Anwendung von IsomlDoc erfolgt in vier Schritten:

 Schritt 1: Werkzeug vorbereiten



 Schritt 4: Erstellen der kompilierten Hilfe

Diese vier Schritte werden im Folgenden näher erläutert.

Schritt 1: Werkzeug vorbereiten

Das Werkzeug IsomlDoc ist Bestandteil der ISOM-Autorenwerkzeuge. Um IsomlDoc verwenden zu können, müssen über die Startmaske des Taurus® Clients die ISOM-Autorenwerkzeuge eingebunden und dann der Mandant ausgewählt werden.

12 von 28

3 Anwenden von IsomlDoc

Abbildung: ISOM-Autorenwerkzeuge einbinden

Vorgang: BZ-11586




3.2

3.2.1







Zum Erstellen der Dokumentation werden die Quelltexte der zu dokumentierenden ISOM/L-Programme benötigt. Die Quelltexte müssen die Dokumentationsanweisungen enthalten. Bevor die Dokumentation erstellt werden kann, werden noch zusätzliche

Dateien benötigt:

Eine HTML-Beschreibung des Kopfbereichs

Eine HTML-Beschreibung des Fußbereichs





Eine Konfigurationsdatei mit Textdefinitionen

Optional eine Datei mit zusätzlichen Dokumentationsseiten

Diese vier Dateien werden im Folgenden kurz beschrieben.

Hinweise:

1. Alle Bilder, die in den HTML-Beschreibungen von Kopf- und

Fußbereich und in den Dokumentationsanweisungen verwendet werden, müssen in dem Verzeichnis abgelegt sein, das über

den Konfigurationsparameter DocImageDir (siehe Kap. 3.3.1)

angegeben wird.

2. In den Voreinstellungen der Konfiguration werden die Bilder und die vier Dateien in dem Verzeichnis

IsomlDocSettings unterhalb des Verzeichnisses der

ISOM/L-Programme erwartet, das über den Konfigurationsparameter OEMScriptsDir festgelegt wird.

HTML-Beschreibungen von Kopf- und Fußbereich

Die beiden HTML-Beschreibungen müssen zusammengefügt ein gültiges HTML-Dokument ergeben. Die Dateinamen werden in den

Konfigurationsparametern DocHeader und DocFooter angegeben.

Die von IsomlDoc erstellte Dokumentation wird zwischen diesen beiden Bereichen eingefügt. Das folgende Beispiel zeigt den

Kopf- und Fußbereich der Dokumentation der ISOM/L-Bibliothek für Serviceautoren (IBS):

13 von 28


Vorgang: BZ-11586





Quellcodeauszug

<?xml version="1.0" encoding="utf-8" standalone="yes"?>

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "">

<html xmlns="http://www.w3.org/1999/xhtml">

<head>

<meta http-equiv="Content-Type" content="text/html;charset=utf-8" />

<title> $title$ </title>

<link href=" $relpath$ isoml.css" rel="stylesheet" type="text/css" />

<link href=" $relpath$ tabs.css" rel="stylesheet" type="text/css" />

</head>

<body bgcolor="#FFFFFF">

<table bgcolor="#FFFFFF" height="80" width="100%">

<tr>

<td><h1>ISOM/L-Bibliothek<br/>für Serviceautoren</h1>

$projectnumber$ </td>

<td><img src=" $relpath$ ifs_header.png" align="right"/></td>

</tr>

</table>

<br/>

Codeauzug: HTML-Beschreibung des Kopfbereichs der IBS

Quellcodeauszug

<br/>

<table bgcolor="#F4F4F4" height="80" width="100%">

<tr><td>Stand: $date$ <br/>IFS Informationstechnik München</td></tr>

</table>

</body>

</html>

Codeauzug: HTML-Beschreibung des Fußbereichs der IBS





In den Beispielen werden für einige Werte Platzhalter verwendet, die von IsomlDoc beim Erstellen der Dokumentation ersetzt werden. Zulässige Platzhalter sind:

$date$ für das Datum der Dokumentenerstellung

$title$ für den Titel, der in der Textdefinition

documentTitle angegeben ist

 $projectname$ für die Projektbezeichnung, die in der

Textdefinition documentName angegeben ist

 $projectnumber$ für die Projektversion, die in der Textdefinition documentVersion angegeben ist

14 von 28


Vorgang: BZ-11586







$relpath$ für den Pfad, in dem die Bilddateien der erstellten Dokumentation abgelegt werden. Die Ablage der

Bilddateien (Ursprungsverzeichnis) für die Dokumentation kann über den Konfigurationsparameter DocImageDir eingestellt werden.

3.2.2 Konfigurationsdatei mit Textdefinitionen

15 von 28


Diese XML-Konfigurationsdatei definiert Texte, die z.B. für die

Beschriftung der Navigationselemente verwendet werden. Der

Dateiname wird im Konfigurationsparameter DocTextSrc angegeben.

Das folgende Beispiel zeigt die Konfigurationsdatei der Dokumentation der ISOM/L-Bibliothek für Serviceautoren (IBS):

Quellcodeauszug

<?xml version="1.0" encoding="utf-8"?>

<language xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"

xsi:noNamespaceSchemaLocation="texts.xsd"

id="de">

<texts>

<text id="documentTitle">ISOM/L-Bibliothek für

Serviceautoren</text>

<text id="documentName">ISOM/L-Bibliothek für Serviceautoren</text>

<text id="documentVersion">Version 6.2.0.0, IFS

Informationstechnik GmbH</text>

<text id="titleNamespaceIndex">Liste der Namensräume</text>

<text id="titleFunctionIndex">Liste der Funktionen</text>

<text id="titlePageIndex">Zusätzliche Informationen</text>

<text id="introNamespaceTable">Hier folgen die Namensräume mit

einer Kurzbeschreibung (wenn verfügbar):</text>

<text id="introFunctionTable">Hier folgt die Aufzählung aller

Funktionen mit Verweisen auf die Namensräume

für jede Funktion:</text>

<text id="introPageList">Hier folgt eine Liste mit

zusammengehörigen Themengebieten:</text>

<text id="titleDeprecatedPage">Veraltete Elemente</text>

<text id="labelDeprecatedEntry">Element</text>

<text id="titleActionPage">Liste der Aktionen</text>

<text id="introActionList">Hier folgt die Übersicht aller Aktionen

in den ISOM/L-Programmen. Zu jeder Aktion ist angegeben, in welchen

Namensräumen Filter- bzw. Ausführungsfunktion oder

Sichtbarkeitsterme angegeben sind.</text>

<text id="titleEcuActionTable">Steuergerätebezogene Aktionen</text>

<text id="titleVehicleActionTable">Fahrzeugbezogene Aktionen</text>

<text id="actionNamespace">Namensraum</text>

<text id="actionFilter">Filterfunktion</text>

<text id="actionExecution">Ausführungsfunktion</text>

Vorgang: BZ-11586





Quellcodeauszug

<text id="actionVisibility">Sichtbarkeit</text>

<text id="navigationMainIndex">Hauptseite</text>

<text id="navigationPageIndex">Zusätzliche Informationen</text>

<text id="Navigationnamespacemainindex">Namensräume</text>

<text id="navigationNamespaceIndex">Liste der Namensräume</text>

<text id="navigationFunctionIndex">Liste der Funktionen</text>

<text id="navigationActionIndex">Liste der Aktionen</text>

<text id="titleNamespace">Namensraum </text>

<text id="labelNamespaceLinkDetails"> Mehr... </text>

<text id="titleNamespaceDetails">Ausführliche Beschreibung</text>

<text id="titleNamespaceList">Namensräume</text>

<text id="titleFunctionList">Funktionen</text>

<text id="titleExtensionList">Erweiterungen</text>

<text id="titleFunctionDescriptions">Dokumentation der

Funktionen</text>

<text id="paragraphAuthor">Autor:</text>

<text id="paragraphDate">Datum:</text>

<text id="paragraphVersion">Version:</text>

<text id="paragraphSince">Seit:</text>

<text id="paragraphDeprecated">Veraltet:</text>

<text id="paragraphUsageHint">Verwendungshinweis:</text>

<text id="paragraphUsageExample">Verwendungsbeispiel:</text>

<text id="paragraphSee">Siehe auch:</text>

<text id="paragraphRemarks">Bemerkungen:</text>

<text id="paragraphNote">Zu beachten:</text>

<text id="paragraphAttention">Achtung:</text>

<text id="paragraphWarning">Warnung:</text>

<text id="paragraphParameter">Parameter:</text>

<text id="paragraphReturn">Rückgabe:</text>

<text id="paragraphException">Ausnahmebehandlung:</text>

<text id="paragraphPreCondition">Vorbedingung:</text>

<text id="paragraphPostCondition">Nachbedingung:</text>

<text id="paragraphInvariant">Invariant:</text>

</texts>

</language>

Codeauszug: Textdefinitionsdatei für IsomlDoc

3.2.3 Zusätzliche Dokumentationsseiten

In einer optionalen Datei können zusätzliche Seiten der Dokumentation angegeben werden. Der Dateiname wird im Konfigurationsparameter DocMainPage angegeben. Üblicherweise wird in dieser Datei die Einleitung der Dokumentation (@mainpage) festgelegt.

16 von 28


Vorgang: BZ-11586





Jede Seite wird in dieser Datei in einem eigenen Blockkommentar beschrieben. Die Dokumentationanweisungen sind die gleichen, die auch für die Dokumentation der Funktionen und Namensräume verwendet werden. Das folgende Beispiel zeigt die gekürzte

Datei aus der Dokumentation der ISOM/L-Bibliothek für Serviceautoren (IBS):

Quellcodeauszug

/** @mainpage Serviceplattform Taurus®: ISOM/L-Bibliothek für Serviceautoren

@anchor mainpage

@author IFS Informationstechnik München, <a href="http://www.ifsit.de/">www.ifs-it.de</a>

@section sec_intro Einführung

...

*/

/** @page pg_processmodel ISOM-Prozessmodell

Die Therapie mit ISOM folgt einem vordefinierten Zustandsmodell.

Jede Phase des Zustandsmodells lässt sich gezielt beeinflussen (inklusive funktional leer lassen).

Die folgende Abbildung zeigt das für Autoren relevante ISOM-Prozessmodell

(Stand 07.04.2010):

@image html Prozessmodell_Autor_html.png

*/

/** @page pg_const Zeichenkettenkonstanten

@anchor const

Auflistung und Erläuterung der Zeichenkettenkonstanten für

Steuergeräteeigenschaften, die der Fachautor in den ISOM/L-Programmen verwenden kann.

...

*/

Codeauszug: Zusätzliche Dokumentationsseite aus der IBS

17 von 28


Vorgang: BZ-11586




3.3

3.3.1



IsomlDoc ist ein Kommandozeilenwerkzeug, das über verschiedene

Konfigurationsparameter gesteuert werden kann. Alle Parameter können in der mitgelieferten Konfigurationsdatei

IsomlDoc.exe.config eingestellt oder als Kommandozeilenparameter übergeben werden. Einstellungen auf der Kommandozeile überschreiben gleichnamige Einstellungen in der Konfigurationsdatei. Die beiden wichtigsten Parameter geben die Pfade zur

ISOM/L-Bibliothek für Serviceautoren (IBS) und zu den anderen zu dokumentierenden ISOM/L-Programmen an:

Quellcodeauszug

IsomlDoc.exe --IsomLibDir=<Pfad zur IBS> --OEMScriptsDir=<Pfad zu anderen

ISOM/L-Programmen>

Codeauszug: Konfigurationsparameter mit Pfaden

Konfiguration

Die Konfigurationsparameter von IsomlDoc sind:

Parameter

Help

Beschreibung zeigt eine Hilfe zu den verfügbaren Kommandozeilenparametern an

DocOutputDir Verzeichnis, in dem die erzeugte HTML-Hilfe ausgegeben wird

DocImageDir Verzeichnis, in dem Bilder abgelegt sind, auf die in der Dokumentation verwiesen wird

DocHeader Name der Datei mit dem Kopfbereich für jede

HTML-Seite der Dokumentation

DocFooter Name der Datei mit dem Fußbereich für jede HTML-

Seite der Dokumentation

DocMainPage Name der Datei mit der Hauptseite (Einleitung) der Dokumentation

DocTextSrc Name der XML-Datei mit übersetzbaren Standardtexten, z.B. dem Titel der Namensraumübersicht

DocExcludeNamespaces Semikolonseparierte Liste von Namensräumen, die nicht dokumentiert werden sollen

DocShortMemberDescriptions in die Tabelle der Funktionen am Beginn jedes

Namensraums eingefügt werden soll

IsomLibDir Verzeichnis mit den Dateien der IBS

18 von 28


Vorgang: BZ-11586





Parameter

OEMScriptsDir

IsomModelDir

Oem

OEMExtensionsDir

Beschreibung

Verzeichnis mit den zu dokumentierenden ISOM/L-

Programmen

Verzeichnis mit den Fahrzeugbeschreibungen

Name des Mandanten

Verzeichnis mit mandantenspezifischen Erweiterungen

AnnotationDataFile

TextCategoryDataFile

Datei mit den Definitionen der zulässigen

Annotationen

Datei mit den Definitionen der zulässigen

Textkategorien

Tabelle: Konfigurationsparameter von IsomlDoc

Das folgende Beispiel zeigt eine typische Konfigurationsdatei.

Die Pfade zu den Dokumentationsdateien sind alle relativ zum

Parameter OEMScriptsDir angegeben.

Quellcodeauszug

<?xml version="1.0" encoding="utf-8" ?>

<configuration>

<configSections>

<sectionGroup name="applicationSettings" type="System.

Configuration.ApplicationSettingsGroup, System, Version=2.0.0.0,

Culture=neutral, PublicKeyToken=b77a5c561934e089" >

<section name="IsomlDoc.Properties.Settings" type="System.

Configuration.ClientSettingsSection, System, Version=2.0.0.0,

Culture=neutral, PublicKeyToken=b77a5c561934e089"

requirePermission="false" />

</sectionGroup>

</configSections>

<applicationSettings>

<IsomlDoc.Properties.Settings>

<setting name=" DocOutputDir " serializeAs="String">

<value>?OEMScriptsDir?/doc/doc</value>

</setting>

<setting name=" DocImageDir " serializeAs="String">

<value>?OEMScriptsDir?/IsomlDocSettings</value>

</setting>

<setting name=" DocHeader " serializeAs="String">

<value>?OEMScriptsDir?/

IsomlDocSettings/HtmlHeader.txt</value>

</setting>

<setting name=" DocFooter " serializeAs="String">

<value>?OEMScriptsDir?/IsomlDocSettings/

HtmlFooter.txt</value>

</setting>

<setting name=" DocMainPage " serializeAs="String">

19 von 28


Vorgang: BZ-11586





Quellcodeauszug

<value>?OEMScriptsDir?/IsomlDocSettings/

MainPage.dox</value>

</setting>

<setting name=" DocTextSrc " serializeAs="String">

<value>?OEMScriptsDir?/

IsomlDocSettings/Documentation_de.xml</value>

</setting>

<setting name=" DocExcludeNamespaces " serializeAs="String">

<value>Example</value>

</setting>

<setting name=" DocShortMemberDescriptions "

serializeAs="Boolean">

<value>True</value>

</setting>

<setting name=" GlobalNamespace " serializeAs="String">

<value>Isom.Global.Processes</value>

</setting>

<setting name=" Oem " serializeAs="String">

<value />

</setting>

<setting name=" IsomLibDir " serializeAs="String">

<value>?IsomBase?\isoml</value>

</setting>

<setting name=" IsomModelDir " serializeAs="String">

<value>?VehicleModel?</value>

</setting>

<setting name=" OEMScriptsDir " serializeAs="String">

<value>?OemIsomL?</value>

</setting>

<setting name=" OEMExtensionsDir " serializeAs="String">

<value>?OemIsomL?\..\bin</value>

</setting>

<setting name=" AnnotationDataFile " serializeAs="String">

<value>?OEMScriptsDir?\AnnotationData.xml</value>

</setting>

<setting name=" TextCategoryDataFile " serializeAs="String">

<value>?OEMScriptsDir?\TextCategoryData.xml</value>

</setting>

<setting name=" SpecializationDataFile " serializeAs="String">

<value>?OEMScriptsDir?\Specialization.xml</value>

</setting>

</IsomlDoc.Properties.Settings>

</applicationSettings>

</configuration>

Codeauszug: Einstellungen d. mitgelieferten Konfigurationsdatei

20 von 28


Vorgang: BZ-11586




3.3.2


Ausgabe

IsomlDoc verwendet die Taurus® Ereignisaufzeichnung, um relevante Ereignisse zu protokollieren. Zusätzlich werden Informationen auf der Konsole ausgegeben. Falls keine Fehler auftreten, sieht die Ausgabe wie folgt aus:

Ausgabe

Dokumentationserstellung beginnen...

ISOM/L-Programme laden...

Zusätzliche Dateien laden...

Dokumentation erstellen...

Dokumentation ausgeben...

Die Dokumentationserstellung ist abgeschlossen.

Die erstellten Dateien befinden sich im Verzeichnis: ...

Konsolenausgabe: Keine Fehler aufgetreten

Fehlermeldungen und Warnungen werden nicht nur über die Ereignisaufzeichnung protokolliert, sondern zusätzlich auf der

Konsole ausgegeben. Das kann wie folgt aussehen:

Ausgabe

Dokumentationserstellung beginnen...

ISOM/L-Programme laden...

Zusätzliche Dateien laden...

Dokumentation erstellen...

Für 846 Funktionen und Namensräume ist keine Dokumentation

vorhanden.

Dokumentation ausgeben...

Die Dokumentationserstellung ist abgeschlossen.

Die erstellten Dateien befinden sich im Verzeichnis: ...

Konsolenausgabe: Fehlermeldung

21 von 28


Vorgang: BZ-11586




3.4


Schritt 4: Erstellen der kompilierten Hilfe

Nachdem das Werkzeug IsomlDoc erfolgreich auf der Kommandozeile aufgerufen wurde, liegt die Dokumentation der ISOM/L-Programme in Form zahlreicher HTML-Seiten vor, die in dem Verzeichnis abgelegt wurden, das über den Konfigurationsparameter

DocOutputDir festgelegt wird. IsomlDoc hat zusätzlich zu den

HTML-Seiten auch Konfigurationsdateien für das Werkzeug

HTML Help Workshop der Firma Microsoft [2] erstellt. Mit diesem

Werkzeug können die HTML-Seiten in ein einzelnes Archiv im Format Compiled HTML Help (*.chm) überführt werden. Das Werkzeug muss dazu zunächst installiert werden. Nach der Installation wird es auf der Kommandozeile aufgerufen:

Quellcodeauszug

<Pfad zum HTMLHelpWorkshop>hhc.exe <DocOutputDir>/index.hhp

Codeauszug: Erzeugen der Hilfe mit HTML Help Workshop

22 von 28


Vorgang: BZ-11586




A

B

23 von 28

Verzeichnisse und Anhänge



Referenzen

Referenz auf

[1] Hoffmann, Simon (IFS): BZ-9758 Handbuch Einführung in die Pro-

grammiersprache ISOM/L, Version 1.0, 05.02.2010.

[2] Microsoft Download Center, HTML Help Workshop and Documentation: http://www.microsoft.com/downloads/details.aspx?FamilyID=00535334c8a6-452f-9aa0-d597d16580cc, Stand: 10.09.2010 16:45 Uhr.

Übersicht aller Dokumentationsanweisungen

Mit Ausnahme der Aufzählungsanweisungen - und -# werden alle

Dokumentationsanweisungen durch das Zeichen @ eingeleitet.

Anweisung

-

Beschreibung

Aufzählungspunkt

Verwendung muss am Anfang einer Zeile stehen. Unterschiedlich tiefe

Einrückungen werden als

Verschachtelung interpretiert.

-# nummerierter Aufzählungspunkt muss am Anfang einer Zeile stehen. Unterschiedlich tiefe

Einrückungen werden als

Verschachtelung interpretiert.

@a Wort Das folgende Wort bezeichnet ein Argument und wird durch einen anderen Zeichensatz hervorgehoben.

@anchor Marke Die folgende Marke wird nicht dargestellt, kann aber von anderen Stellen der Dokumentation aus referenziert werden.

@attention markiert einen Absatz mit einem Hinweis wird im laufenden Text verwendet, um auf ein Funktionsargument zu verweisen steht üblicherweise auf einer eigenen Zeile, z.B. vor einem

Bild, auf das in einem Absatz verwiesen wird steht am Anfang einer Zeile.

Der Absatz-Inhalt kann auf der gleichen oder der folgenden

Zeile beginnen.

@author markiert einen Absatz, in steht am Anfang einer Zeile. dem ein Verfasser angegeben wird


Zeile beginnen.

Vorgang: BZ-11586





Anweisung

@b Wort

Beschreibung

Das folgende Wort wird durch Fettschrift hervorgehoben.

Verwendung wird im laufenden Text verwendet, um ein Wort hervorzuheben

@brief markiert einen Absatz mit einer Kurzbeschreibung einer Funktion oder eines

Namensraums steht am Anfang einer Zeile.


Zeile beginnen.

@c Wort Das folgende Wort bezeichwird im laufenden Text verwen-

net ein Code-Element und det, um eine ISOM/L-Anweisung wird durch einen anderen

Zeichensatz hervorgehoben. hervorzuheben

@code @endcode Die Zeilen zwischen den beiden Anweisungen werden als Quelltextbeispiel betrachtet. Formatierungen

(Umbrüche und Einrückungen) bleiben erhalten.

Diese Anweisungen stehen immer einzeln in eigenen Zeilen.

@date Markiert eine Datumsangabe; steht am Anfang einer Zeile.

üblicherweise die letzte

Bearbeitung


Zeile beginnen.

@deprecated markiert einen Absatz, in dem beschrieben wird, seit wann die dokumentierte

Funktion veraltet ist.

@details steht am Anfang einer Zeile.


Zeile beginnen. markiert einen Absatz mit der ausführlichen Beschreibung einer Funktion oder eines Namensraums steht am Anfang einer Zeile.


Zeile beginnen.

@e (auch @em) Das folgende Wort wird durch kursive Schrift hervorgehoben.

@exception Beschreibt eine Bedingung, unter der die Funktion ein

Void-Objekt zurückgibt wird im laufenden Text verwendet, um ein Wort hervorzuheben steht am Anfang einer Zeile.


Zeile beginnen.

@if @endif Die Zeilen zwischen den beiden Anweisungen werden ignoriert. Die Bedingung wird momentan nicht ausgewertet.

Diese Anweisungen stehen immer einzeln in eigenen Zeilen.

24 von 28


Vorgang: BZ-11586





Anweisung

@image Format

Dateiname

Beschreibung verweist auf die Bilddatei

Dateiname, die an dieser

Stelle einzufügen ist, falls das Format dem Ausgabeformat (z.B. HTML) entspricht.

@invariant markiert einen Absatz, in dem Invarianzen der Funktion beschrieben werden

Verwendung steht immer in einer eigenen

Zeile. Der Text nach den ersten beiden Parametern wird als

Bildunterschrift verwendet. steht am Anfang einer Zeile.


Zeile beginnen.

@li Aufzählungspunkt muss am Anfang einer Zeile stehen. Unterschiedlich tiefe

Einrückungen werden als Verschachtelung interpretiert

@mainpage markiert einen Abschnitt, der den Inhalt der Hauptseite enthält. Darf nur einmal in einer Dokumentation vorkommen.

@name

@{

@} steht immer in einer eigenen

Zeile. Der Text auf dieser

Zeile wird als Überschrift interpretiert. enthält die Beschreibung für den folgenden Block.

Blöcke umfassen üblicherweise mehrere Funktionen, die dann in der Liste der

Funktionen (am Anfang eines

Namensraums) in einem eigenen Absatz beschrieben steht am Anfang einer Zeile.


Zeile beginnen. werden. Blöcke können nicht geschachtelt werden!

Anfang eines Blocks. Diese Anweisungen stehen immer einzeln in einer eigenen Zeile.

Ende eines Blocks. Diese Anweisungen stehen immer einzeln in einer eigenen Zeile.

@note markiert einen Absatz mit einer Anmerkung steht am Anfang einer Zeile.


Zeile beginnen.

25 von 28


Vorgang: BZ-11586





Anweisung

@p

@page Seiten- name

@par

Beschreibung Verwendung

Das folgende Wort bezeichwird im laufenden Text verwennet einen Parameter und det, um auf einen Funktionspawird durch einen anderen

Zeichensatz hervorgehoben. rameter zu verweisen markiert einen Abschnitt, der den Inhalt der Seite

Seitenname enthält steht immer in einer eigenen

Zeile. Text nach dem Parameter

Seitenname wird als Überschrift interpretiert. Der Seitenname kann z.B. als Ziel für Verweise dienen. markiert einen neuen Absatz

Der Absatz-Inhalt beginnt immer in der folgenden Zeile. In der gleichen Zeile kann eine optionale Überschrift für den Absatz angegeben werden.

@param Parame-

tername beschreibt den Funktionsparameter Parametername steht am Anfang einer Zeile.

Das erste folgende Wort ist der

Name des Parameters, der Rest des Absatzes ist die Beschreibung.

@pre beschreibt eine Vorbedingung einer Funktion steht am Anfang einer Zeile.


Zeile beginnen.

@post beschreibt eine Nachbedingung einer Funktion steht am Anfang einer Zeile.


Zeile beginnen.

@ref Ziel erzeugt einen Verweis auf das Ziel. Das Ziel kann ments (Funktion oder Namensraum) kann im laufenden Text verwendet werden. Folgt auf den Paraeine Marke (siehe @anchor) meter Ziel Text in Anführungssein, ein benannter Absatz, zeichen, so wird dieser Text ein Kapitel oder der Name eines dokumentierten Eleals Beschriftung des Verweises verwendet; sonst wird als Beschriftung der Name des Ziels genutzt (z.B. bei Verweisen auf

Funktionen) oder dessen Überschrift (z.B. bei Verweisen auf

Seiten und Kapitel).

@remarks markiert einen Absatz mit einer Bemerkung steht am Anfang einer Zeile.


Zeile beginnen.

26 von 28


Vorgang: BZ-11586





Anweisung

@return (auch

@returns)

Beschreibung Verwendung beschreibt den Rückgabewert einer Funktion steht am Anfang einer Zeile.


Zeile beginnen.

@see (auch

@sa) markiert einen Absatz mit

Verweisen („Siehe auch“) steht am Anfang einer Zeile.


Zeile beginnen.

@section Name beschreibt das Kapitel Name steht immer in einer eigenen

Zeile. Der Text nach dem Parameter Name wird als Überschrift interpretiert. Der Kapitelname kann z.B. als Ziel für Verweise dienen.

@subsection

Name beschreibt das Unterkapitel

Name steht immer in einer eigenen

Zeile. Der Text nach dem Parameter Name wird als Überschrift interpretiert. Der Kapitelname kann z.B. als Ziel für Verweise dienen.

@subsubsection

Name beschreibt das Unterkapitel steht immer in einer eigenen

Name der zweiten Ebene Zeile. Der Text nach dem Parameter Name wird als Überschrift interpretiert. Der Kapitelname kann z.B. als Ziel für Verweise dienen.

@since markiert einen Absatz, in dem beschrieben wird, seit wann die dokumentierte

Funktion verfügbar ist steht am Anfang einer Zeile.


Zeile beginnen.

@subpage Sei- tenname markiert eine Abschnitt, der den Inhalt der untergeordneten Seite Seitenname enthält steht immer in einer eigenen

Zeile. Der Text nach dem Parameter Seitenname wird als Überschrift interpretiert. Der

Seitenname kann z.B. als Ziel für Verweise dienen.

@usagehints markiert einen Absatz mit

Verwendungshinweisen steht am Anfang einer Zeile.


Zeile beginnen.

@usageexample markiert einen Absatz mit

Verwendungsbeispielen steht am Anfang einer Zeile.


Zeile beginnen.

27 von 28


Vorgang: BZ-11586





Anweisung

@version

Beschreibung markiert einen Absatz, in dem eine Version angegeben wird

Verwendung steht am Anfang einer Zeile.


Zeile beginnen.

@verbatim

@endverbatim

Die Zeilen zwischen den beiden Anweisungen sollen

wörtlich übernommen werden.

Formatierungen (Umbrüche

Diese Anweisungen stehen immer einzeln in eigenen Zeilen. und Einrückungen) bleiben erhalten.

@warning markiert einen Absatz mit einer Warnung steht am Anfang einer Zeile.


Zeile beginnen.

Tabelle: Alphabetische Liste der Dokumentationsanweisungen

28 von 28


Vorgang: BZ-11586



Dokumentieren von Quelltexten mit IsomlDoc

Bedienungsanleitung

Dokumentinformationen

Inhalt

1

Einleitung

2 Dokumentationsanweisungen für IsomlDoc

Allgemeine Hinweise 2.1

2.2 Grundlegende Dokumentationsanweisungen

2.3

Dokumentationsanweisungen für Funktionen

2.4 Weitere Dokumentationsanweisungen

3

3.1

Anwenden von IsomlDoc

Schritt 1: Werkzeug vorbereiten

3.2

3.2.1

Schritt 2: Quelltexte bereitstellen

HTML-Beschreibungen von Kopf- und Fußbereich

3.2.2 Konfigurationsdatei mit Textdefinitionen

3.2.3 Zusätzliche Dokumentationsseiten

3.3

3.3.1

Schritt 3: Konfiguration und Aufruf des Werkzeugs

Konfiguration

3.3.2

Ausgabe

3.4

Schritt 4: Erstellen der kompilierten Hilfe

A

B

Verzeichnisse und Anhänge

Referenzen

Übersicht aller Dokumentationsanweisungen

Related manuals

Socomec

Software solution