Galileo Computing < openbook > Galileo Computing - Professionelle Bücher. Auch für Einsteiger.
Professionelle Bücher. Auch für Einsteiger.

Inhaltsverzeichnis
Vorwort zur 5. Auflage
1 Allgemeine Einführung in .NET
2 Grundlagen der Sprache C#
3 Klassendesign
4 Vererbung, Polymorphie und Interfaces
5 Delegates und Ereignisse
6 Weitere .NET-Datentypen
7 Weitere Möglichkeiten von C#
8 Auflistungsklassen (Collections)
9 Fehlerbehandlung und Debugging
10 LINQ to Objects
11 Multithreading und die Task Parallel Library (TPL)
12 Arbeiten mit Dateien und Streams
13 Binäre Serialisierung
14 Einige wichtige .NET-Klassen
15 Projektmanagement und Visual Studio 2010
16 XML
17 WPF – Die Grundlagen
18 WPF-Containerelemente
19 WPF-Steuerelemente
20 Konzepte der WPF
21 Datenbindung
22 2D-Grafik
23 ADO.NET – verbindungsorientierte Objekte
24 ADO.NET – Das Command-Objekt
25 ADO.NET – Der SqlDataAdapter
26 ADO.NET – Daten im lokalen Speicher
27 ADO.NET – Aktualisieren der Datenbank
28 Stark typisierte DataSets
29 LINQ to SQL
30 Weitergabe von Anwendungen
Stichwort

Buch bestellen
Ihre Meinung?

Spacer
<< zurück
Visual C# 2010 von Andreas Kühnel
Das umfassende Handbuch
Buch: Visual C# 2010

Visual C# 2010
geb., mit DVD
1295 S., 49,90 Euro
Rheinwerk Computing
ISBN 978-3-8362-1552-7
Pfeil 15 Projektmanagement und Visual Studio 2010
Pfeil 15.1 Der Projekttyp »Klassenbibliothek«
Pfeil 15.1.1 Mehrere Projekte in einer Projektmappe verwalten
Pfeil 15.1.2 Die Zugriffsmodifizierer »public« und »internal«
Pfeil 15.1.3 Friend-Assemblys
Pfeil 15.1.4 Einbinden einer Klassenbibliothek
Pfeil 15.2 Assemblys
Pfeil 15.2.1 Konzept der Assemblys
Pfeil 15.2.2 Allgemeine Beschreibung privater und globaler Assemblys
Pfeil 15.2.3 Struktur einer Assembly
Pfeil 15.2.4 Globale Assemblys
Pfeil 15.3 Konfigurationsdateien
Pfeil 15.3.1 Einführung
Pfeil 15.3.2 Die verschiedenen Konfigurationsdateien
Pfeil 15.3.3 Struktur einer Anwendungskonfigurationsdatei
Pfeil 15.3.4 Anwendungskonfigurationsdatei mit Visual Studio 2010 bereitstellen
Pfeil 15.3.5 Einträge der Anwendungskonfigurationsdatei auswerten
Pfeil 15.3.6 Editierbare, anwendungsbezogene Einträge mit <appSettings>
Pfeil 15.4 Versionsumleitung in einer Konfigurationsdatei
Pfeil 15.4.1 Herausgeberrichtliniendatei
Pfeil 15.5 XML-Dokumentation
Pfeil 15.5.1 Prinzip der XML-Dokumentation
Pfeil 15.5.2 XML-Kommentar-Tags
Pfeil 15.5.3 Generieren der XML-Dokumentationsdatei
Pfeil 15.6 Der Klassendesigner (Class Designer)
Pfeil 15.6.1 Ein typisches Klassendiagramm
Pfeil 15.6.2 Hinzufügen und Ansicht von Klassendiagrammen
Pfeil 15.6.3 Die Toolbox des Klassendesigners
Pfeil 15.6.4 Das Fenster »Klassendetails«
Pfeil 15.6.5 Klassendiagramme als Bilder exportieren
Pfeil 15.7 Refactoring
Pfeil 15.7.1 Methode extrahieren
Pfeil 15.7.2 Bezeichner umbenennen
Pfeil 15.7.3 Felder einkapseln
Pfeil 15.8 Code Snippets (Codeausschnitte)
Pfeil 15.8.1 Codeausschnitte einfügen
Pfeil 15.8.2 Anatomie eines Codeausschnitts


Galileo Computing - Zum Seitenanfang

15.5 XML-Dokumentation Zur nächsten ÜberschriftZur vorigen Überschrift

In C# lässt sich der Programmcode bereits innerhalb des Codeeditors dokumentieren. Dazu werden XML-Tags in spezielle Kommentarfelder des Quellcodes eingefügt, die unmittelbar vor dem Codeblock stehen, auf den sie sich beziehen. Auf diese Weise können Typen wie Klassen, Enumerationen, Delegates, Schnittstellen und Strukturen sowie deren Eigenschaften, Felder, Methoden, Ereignisse usw. beschrieben werden.

Der Clou bei der XML-Dokumentation ist, den Code mit zusätzlichen Informationen zu versorgen, die sowohl in der IntelliSense-Hilfe, als auch im Objektkatalog nachzulesen sind. Darüber hinaus lässt sich die XML-Dokumentation auch in XML-Dateien veröffentlichen. Die XML-Dokumentationsdateien ersetzen sicherlich nicht eine konventionelle und aufwendige Dokumentation, können aber dennoch zumindest unterstützend bei der Entwicklung hilfreich sein.


Galileo Computing - Zum Seitenanfang

15.5.1 Prinzip der XML-Dokumentation Zur nächsten ÜberschriftZur vorigen Überschrift

Nehmen wir zu Demonstrationszwecken die Methode GetArea der Klasse Circle, die wir dokumentieren möchten:


public static double GetArea(int radius) {
  return Math.PI * Math.Pow(radius, 2);
}

XML-Dokumentationen werden dem Element vorangestellt, das dokumentiert werden soll. Eingeleitet werden die Kommentarfelder mit drei Schrägstrichen. Wenn Sie den Cursor vor das zu dokumentierende Element positionieren und die drei einleitenden Schrägstriche in den Code vor eine Klassendefinition schreiben, wird der folgende XML-Kommentar automatisch ergänzt:


/// <summary>
/// 
/// </summary>
/// <param name="radius"></param>
/// <returns></returns>

Zwischen dem ein- und ausleitenden <summary>-Tag können Sie eine Beschreibung eintragen, die später vom zu generierenden XML-Dokument übernommen wird. Zudem wird die Beschreibung in der IntelliSense-Hilfe und im Objektkatalog angezeigt. Die Beschreibung zwischen <summary> und </summary> sollte kurz gehalten werden. Für ausführlichere Beschreibungen steht Ihnen mit <remarks> ein geeigneteres Tag zur Verfügung.

Sie können sehen, dass über <summary> hinaus noch weitere vordefinierte XML-Dokumentationstags angeboten werden. Das Attribut name des <param>-Tags enthält den Bezeichner des Parameters. Zwischen dem ein- und ausleitenden Tag dürfen Sie auch eine spezifische Beschreibung eintragen. Diese wird vom späteren XML-Dokument übernommen und im Objektkatalog angezeigt, allerdings nicht in IntelliSense. <returns> dient zur Beschreibung des Rückgabewertes. Für dieses Tag gilt hinsichtlich der Anzeige dasselbe wie für <param>.

Sehen wir uns an dieser Stelle einmal einen etwas aufwendigeren XML-Kommentar sowie dessen Auswirkungen an:


/// <summary>
/// Berechnet die Fläche eines beliebigen Kreises
/// </summary>
/// <param name="radius">Geben Sie hier den Radius des zu 
                         berechnenden Kreises an
/// </param>
/// <returns>Liefert die Kreisfläche</returns>
/// <remarks>Die Methode ist 'static' definiert.
/// <para>Sie müssen diese Methode auf dem Klassenbezeichner aufrufen.
/// </para>
/// </remarks>
public static double GetArea(double radius) {
  return Math.PI * Math.Pow(radius, 2);
}

Mit dem Objektkatalog, der über das Menü Ansicht geöffnet wird, können Sie Objekte (Namespaces, Klassen, Strukturen, Schnittstellen, Typen, Enumerationen usw.) und ihre Member (Eigenschaften, Methoden, Ereignisse, Variablen, Konstanten, Enumerationselemente) aus verschiedenen Komponenten suchen und überprüfen. Bei diesen Komponenten kann es sich um Projekte in der Projektmappe, um referenzierte Komponenten innerhalb dieser Projekte und um externe Komponenten handeln.

Schauen Sie sich im Objektkatalog nun die Ausgabe zu der Methode GetArea an (siehe Abbildung 15.22).

Abbildung 15.22 Ausgabe des XML-Kommentars im Objektkatalog

Ich glaube, dass Sie auch ohne eine langatmige Beschreibung erkennen können, welche Bereiche den einzelnen Tags zugeordnet werden. Im Codeeditor hingegen wird nur die Beschreibung angezeigt, die hinter <summary> angegeben ist (siehe Abbildung 15.23).

Abbildung 15.23 Anzeige der XML-Dokumentinformationen im Codeeditor


Galileo Computing - Zum Seitenanfang

15.5.2 XML-Kommentar-Tags Zur nächsten ÜberschriftZur vorigen Überschrift

Ich habe Ihnen bisher einige, aber nicht alle Tags vorgestellt, die zur XML-Dokumentation dienen. In Tabelle 15.6 stelle ich Ihnen alle der Übersicht halber vor.


Tabelle 15.6 Vordefinierte XML-Dokumentations-Tags

XML-Dokumentations-Tag Beschreibung

<c>

Kennzeichnet, dass dieser Text in einer Beschreibung als Code erscheinen soll.

<code>

Kennzeichnet, dass mehrere Zeilen als Code dargestellt werden sollen.

<example>

Kennzeichnet ein Beispiel zur Verwendung einer Klasse oder Methode.

<exception>

Wird zur Dokumentation der Ausnahmen verwendet, die von einer Klasse ausgelöst werden können.

<include>

Mit diesem Tag kann auf Kommentare in anderen Dateien verwiesen werden, die die Typen und Member im Quellcode beschreiben.

<list>

Kennzeichnet eine Liste von Elementen.

<para>

Dieses Tag ist für die Verwendung innerhalb eines Tags, wie beispielsweise <summary>, <remarks> und <returns>, vorgesehen und ermöglicht die Strukturierung des Texts.

<param>

Dieses Tag sollte im Kommentar für eine Methodendeklaration verwendet werden, um einen der Parameter der Methode zu beschreiben. Der Text wird in IntelliSense und im Objektkatalog über Codekommentare angezeigt.

<paramref>

Ein Verweis auf einen anderen Parameter

<permission>

Wird zur Beschreibung der Zugriffsberechtigungen für ein Member verwendet.

<remarks>

Eine Beschreibung des Elements, die <summary> ergänzt. Die Informationen werden im Objektkatalog angezeigt.

<returns>

Dokumentiert den Rückgabewert einer Methode.

<see>

Wird zum Querverweis auf verwandte Elemente verwendet.

<seealso>

Eine Verknüpfung zum »Siehe auch«-Abschnitt der Dokumentation

<summary>

Eine kurze Beschreibung des Elements, die in IntelliSense und im Objektkatalog angezeigt wird

<typeparam>

Dieses Tag sollte in dem Kommentar für einen generischen Typ oder eine Methodendeklaration zum Beschreiben eines Typparameters verwendet werden. Fügen Sie für jeden Typparameter des generischen Typs oder der Methode ein Tag hinzu.

<typeparamref>

Der Name des Typparameters

<value>

Beschreibt den Wert einer Eigenschaft.



Galileo Computing - Zum Seitenanfang

15.5.3 Generieren der XML-Dokumentationsdatei topZur vorigen Überschrift

Die Typen und deren Member mit XML-Kommentar zu versehen reicht zwar schon aus, um im Objektkatalog oder in der IntelliSense-Hilfe den Benutzer mit grundlegenden Informationen zu versorgen, aber damit wird nicht sofort ein XML-Dokument erzeugt, das sich beispielsweise zu einer Integration in eine Hilfe eignet und durchaus auch noch weitere Informationen bereitstellen kann.

Um aus den XML-Kommentaren eine XML-Dokumentationsdatei zu erzeugen, müssen Sie das Projekteigenschaftsfenster öffnen. Doppelklicken Sie dazu auf den Knoten Properties. Am linken Rand sind mehrere Laschen gruppiert; klicken Sie hier auf Erstellen (siehe Abbildung 15.24). Auf der nun angezeigten Registerkarte setzen Sie ein Häkchen neben XML-Dokumentationsdatei. Damit ist alles Notwendige erledigt. Die Vorgabe des Ausgabeordners und den Bezeichner der XML-Dokumentationsdatei können Sie im Bedarfsfall auch ändern.

Wir sollten auch einen Blick in das erzeugte Dokument werfen. Das gesamte Dokument wird in <doc>-Tags eingefasst. <doc> umfasst neben der Bekanntgabe des Dokumentationsnamens in <assembly> im Bereich <members> auch alle Tags, die wir im Codeeditor aufgeführt haben.


<?xml version="1.0"?>
<doc>
  <assembly>
    <name>CircleApplication6</name>
  </assembly>
  <members>
     <member name="M:CircleApplication.Circle.
                              GetFlaeche(System.Double)">
     <summary> Berechnet die Fläche eines beliebigen Kreises
     </summary>
     <param name="radius">Geben Sie hier den Radius des zu
                          berechnenden Kreises an
    </param>
    <returns>Liefert die Kreisfläche</returns>
    <remarks>Die Methode ist als 'static' definiert.
    <para>Sie müssen diese Methode auf dem Klassenbezeichner aufrufen.
    </para>
    </remarks>
    </member>
  </members>
</doc>

Abbildung 15.24 So stellen Sie die Erzeugung eines XML-Dokumentationsdokuments ein.



Ihr Kommentar

Wie hat Ihnen das <openbook> gefallen? Wir freuen uns immer über Ihre freundlichen und kritischen Rückmeldungen. >> Zum Feedback-Formular
<< zurück
  Zum Katalog
Zum Katalog: Visual C# 2010

Visual C# 2010
Jetzt bestellen


 Ihre Meinung?
Wie hat Ihnen das <openbook> gefallen?
Ihre Meinung

 Buchempfehlungen
Zum Katalog: Professionell entwickeln mit Visual C# 2012






 Professionell
 entwickeln mit
 Visual C# 2012


Zum Katalog: Windows Presentation Foundation






 Windows Presentation
 Foundation


Zum Katalog: Schrödinger programmiert C++






 Schrödinger
 programmiert C++


Zum Katalog: C++ Handbuch






 C++ Handbuch


Zum Katalog: C/C++






 C/C++


 Shopping
Versandkostenfrei bestellen in Deutschland und Österreich
InfoInfo




Copyright © Rheinwerk Verlag GmbH 2010
Für Ihren privaten Gebrauch dürfen Sie die Online-Version natürlich ausdrucken. Ansonsten unterliegt das <openbook> denselben Bestimmungen, wie die gebundene Ausgabe: Das Werk einschließlich aller seiner Teile ist urheberrechtlich geschützt. Alle Rechte vorbehalten einschließlich der Vervielfältigung, Übersetzung, Mikroverfilmung sowie Einspeicherung und Verarbeitung in elektronischen Systemen.


[Rheinwerk Computing]

Rheinwerk Verlag GmbH, Rheinwerkallee 4, 53227 Bonn, Tel.: 0228.42150.0, Fax 0228.42150.77, service@rheinwerk-verlag.de