Dokumentation zu C♯ 

Die Dokumentation einer Bibliothek ist wie ein Wörterbuch für jene Bibliothek, sie erklärt die Wörter jener Bibliothek. Sie wird manchmal auch als „API-Spezifikation “ bezeichnet.

Die .NET-Framework -API-Dokumentation ist eine Sammlung von Erklärungen zur Bedeutung von Namen, welche von der Standardbibliothek von Dotnet  („.NET“) definiert werden. Alle diese Namen lassen sich in C♯ -Programmen verwenden.

Die .NET-Framework -API-Dokumentation läßt sich im World-Wide Web  lesen. Der Typ einer von der Standardbibliothek festgelegten Konstanten kann in der .NET-Framework -API-Dokumentation nachgelesen werden. Dort finden sich auch weitere Erklärungen zur Bedeutung solch einer Konstanten.

»global::System.Int32.MaxValue« [Dokumentation, gekürzt, teilweise modifiziert oder übersetzt]

.Net Framework Class Library
  Namespace: global::System
    Type: global::System.Int32
      public const int MaxValue
        Der maximale Wert des Datentyps "int".

Wir sehen in der Dokumentation des Bezeichners »MaxValue« aus der Struktur »global::System.Int32«:

• den Namen des Namensraums der Struktur: »global::System«,
• die Gattung »structure« (Struktur) und den Namen »Int32« der Struktur,
• die Spezifikation des Feldes mit dem Typ »int«, und dem Namen »MaxValue«,
• sowie schließlich eine englischsprachigen Beschreibung der Bedeutung dieses Feldes.

In diesem Kurs geben wir zu englischsprachigen Texten meist auch eine deutsche Übersetzung an oder ersetzen den englischsprachigen Text gleich durch eine deutsche Übersetzung.

Die .NET-Framework -API-Dokumentation und die C♯LS  sind die beiden wichtigsten Original-Quellen zur Programmiersprache C♯. Während die C♯LS  die eigentliche Programmiersprache beschreibt (einschließlich von – beispielsweise – Literalen, Operatoren und elementaren Typen), beschreibt die .NET-Framework -API-Dokumentation die Standardbibliothek der Programmiersprache.

Die Dokumentation eines Typs  hält fest, welche Einträge der Typ enthält. In der Dokumentation der Struktur »global::System.Int32« findet man unter der Überschrift „Fields“ eine kurze Beschreibung des Feldes »MaxValue«, welche mit einer separaten Seite verbunden ist, die dann nur dieses Feld beschreibt.

Gleichzeitig findet man in der Dokumentation der Struktur »global::System.Int32« hinter dem Etikett „Namespace:“ eine Verbindung zur Dokumentation des Namensraumes dieser Struktur, also des Namensraums »global::System«.

Adressen

Adresse der Dokumentation des Feldes »MaxValue« der Struktur »global::System.Int32«

msdn.microsoft.com/library/system.int32.maxvalue

Wenn keine bestimmte Sprache (wie »en-us« unten) und keine bestimmte Versionsnummer (wie »110« unten) angegeben ist, so kann mit einer Adresse, die den vollständig qualifizierten Namen (ohne »global::«) enthält, die Dokumentation zu einem Namen gefunden werden. Auch das weiter unten zu findende ».aspx« kann bei manueller Eingabe der Adresse entfallen.

Adresse der englischsprachigen Dokumentation des Feldes »MaxValue« der Struktur »global::System.Int32« in Version 4.5 (110) der .NET-Standardbibliothek

http://msdn.microsoft.com/en-us/library/system.int32.maxvalue(v=vs.110).aspx

Adresse der deutschsprachigen Dokumentation des Feldes »MaxValue« der Struktur »global::System.Int32«

http://msdn.microsoft.com/de-de/library/system.int32.maxvalue(v=vs.110).aspx

Die deutschsprachigen Dokumentationsseiten sind manchmal automatisch übersetzt und dann nicht immer gut lesbar.

Adresse der englischsprachigen Dokumentation der Struktur »global::System.Int32«

http://msdn.microsoft.com/en-us/library/system.int32(v=vs.110).aspx

Adresse der englischsprachigen Dokumentation des globalen Namensraumes »global::System«

http://msdn.microsoft.com/en-us/library/system(v=vs.110).aspx

Adresse der englischsprachigen Dokumentation der gesamten “.NET Framework Class Library ” (Version 4.5 und 4.6)

http://msdn.microsoft.com/en-us/library/gg145045(v=vs.110).aspx

Diese Seite enthält alle globalen Namensräume (Hauptinhaltsverzeichnis, Haupteinstiegspunkt), so daß von hier aus im Prinzip jeder Eintrag der gesamten Bibliothek erreichbar ist.

Adresse der englischsprachigen Dokumentation der gesamten “.NET Framework Class Library ” (Version 4)

http://msdn.microsoft.com/en-us/library/gg145045(v=vs.100).aspx

.NET for Windows Store apps

HTTP://msdn.microsoft.com/en-us/library/br230302.aspx

Diese Seite enthält die Namensräume von “.NET for Windows Store apps ”, eine Bibliothek, die das Schreiben von Windows-Store-apps  mit .NET  erlaubt. Dabei wird “Windows.UI.Xaml ” verwendet.

Direktzugriff mit einer Suchmaschine

Manchmal kann mit einer Suchmaschine direkt auf eine Seite zugegriffen werden, die einen Typ oder einen Eintrag dokumentiert, indem man nach dem Namen des Typs oder Eintrags sucht. Manchmal ist es nötig, noch den Namensraum oder die .NET-Framework -API-Version hinzuzufügen, wie beispielsweise »110 System Int32« oder »110 Int32 MaxValue«.

Zur englischen Sprache

Obwohl die Original-Spezifikation und Dokumentation des .NET-Framework  in englisch verfaßt sind, ist es nicht  nötig, Englisch zu lernen, um C♯  zu erlernen. Denn die wichtigsten Informationen aus der Spezifikation und der Dokumentation von C♯  können auch in deutschsprachigen Nachschlagewerken nachgelesen werden.

»public«

Wir sehen die Konstante  in der Dokumentations mit »public« gekennzeichnet. Dies bedeutet – etwas vereinfacht gesagt –, daß für diese Konstante nicht „versteckt“ ist. Wäre sie versteckt, könnten wir sie allerdings ohnehin nicht in der Dokumentation sehen oder verwenden.

Dokumentation von Eigenschaften

»global::System.Console.Title« ist eine Eigenschaft, die den Titel des Konsolenfensters, in dem die Ausgaben unseres Programmes erscheinen, darstellt.

Wir zeigen hier eine vereinfachte Dokumentation und ein Beispielprogramm dazu.

»global::System.Console.Title« [Dokumentation, gekürzt, teilweise modifiziert oder übersetzt]

msdn.microsoft.com/library/system.console.title
.Net Framework Class Library
  Namespace: global::System
    Type: global::System.String
      public static string Title
        The string in the title of the console.
        Die Zeichenfolge im Titel der Konsole

Program.cs

public static class Program
{ public static void Main()
  { global::System.Console.WriteLine
    ( global::System.Console.Title ); }}

global::System.Console.Out

C:\example\Main.cmd

Die Reihenfolge des Lesens der Dokumentation

Wenn man sich vollständig über einen Eintrag, wie beispielsweise »global::System.Int32.MaxValue«, informieren will, dann sollte man die Dokumentation zu allen Namen lesen, die sich durch Entfernen eines Teils hinter einem Punkte ergeben.

Die Bestandteile von »global::System.Int32.MaxValue«

global::System
global::System.Int32
global::System.Int32.MaxValue

Daher sollte man in dieser Reihenfolge lesen:

• Den Beschreibungstext in der Dokumentation der Namensräume (also beispielsweise von »System«). Er enthält Informationen, die für alle Teile des Namensraums gemeinsam gelten. (Es ist nicht nötig, die kurzen Beschreibungen aller Einträge zu lesen.)
• Den Einführungstext der Dokumentation des Typs (also beispielsweise von »System.Int32«). Er enthält Informationen, die für alle Teile des Typs gemeinsam gelten. (Es ist nicht nötig, die Beschreibung der einzelnen Einträge zu lesen.) Und schließlich
• die Dokumentation des eigentlichen Eintrags (also beispielsweise von »System.Int32.MaxValue«).

Das folgenden Begriffssystem zur Beschreibung von Teilen der Dokumentation wird in den zehner Jahren entwickelt. Während dieser Entwicklung ist es möglich, daß die darin vorkommenden Begriffe („Lemma“, „Oberfläche“, „Proklamation“, „Prosa“, „Klausel“ und so weiter) in verschiedenen Quellen noch nicht einheitlich verwendet werden.

Lemmata

Wir bezeichnen eine Angabe, die einen bestimmten Eintrag einer Klasse bestimmt, auch als ein Lemma  (Genitiv „des Lemma“, Plural „die Lemmata“).

Im Falle des Feldes »global::System.Int32.MaxValue« ist das Lemma einfach nur »MaxValue«, denn wenn der Typ »global::System.Int32« schon feststeht, dann wird durch das Lemma »MaxValue« ein bestimmtes Feld der Klasse eindeutig und genau bestimmt.

Wir sprechen hier von „Lemmata“ und nicht von „Feldern“, weil wir später noch andere Lemmata kennenlernen werden, die keine Felder sind.

Proklamationen

In der Dokumentation findet man oft eine Zeile, die das Lemma und einige Aussagen dazu in einer formalisierten Weise enthält. Sie wird oft in einer dicktengleichen Schrift gesetzt (Schreibmaschinenschrift).

Solch eine Angabe bezeichnen wir als eine Proklamation.

Die Proklamation zum Lemma »MaxValue« lautet beispielsweise »public const int MaxValue«. Es besagt, daß das Feld »MaxValue« nicht versteckt sowie ein Konstante ist und den Typ »int« hat.

Die Proklamation »public const int MaxValue«

      public                 const                  int                MaxValue
Besagt, dass dieses   Besagt, dass dieses   Besagt, dass dieses    Das Lemma ist der
    Lemma nicht           Lemma eine        Lemma den Typ "int"    Gegenstand der
  versteckt ist.        Konstante ist.              hat.               Aussagen.
                                                                    
    Aussage 1              Aussage 2              Aussage 3             Lemma

Eine Proklamation wird manchmal auch mit einem Semikolon an ihrem Ende geschrieben, wie beispielsweise »public const int MaxValue;«. Solch ein Semikolon hat allerdings keine weitere inhaltliche Bedeutung, höchstens könnte man sagen, daß es das Ende der Proklamation kennzeichne.

Klauseln

Die Verbindung einer Proklamation mit verbindlichen, nicht-vagen Aussagen über das Lemma, die in einer natürlichen Sprache (wie Deutsch oder Englisch) gemacht werden, nennen wir eine Klausel.

Die folgende Klausel besteht aus einer Proklamation in der ersten Zeile und einem deutschsprachigen Text in der zweiten Zeile.

Klausel zum Lemma »MaxValue«

public const int MaxValue
Der maximale Wert des Datentyps "int".

Die obenstehende Klausel enthält drei Aussagen:

• Das Lemma ist nicht versteckt (»public«).
• Das Lemma ist eine Konstante.
• Das Lemma hat den Typ »int«.
• Der Wert (die Bedeutung) des Lemmas ist der maximale Wert des Datentyps »int«.

Die ersten drei dieser Aussagen sind formal in der Proklamation enthalten, die dritte auf deutsch in der Klausel.

Für die Programmierung wäre es eigentlich gut, wenn man alle Aussagen formal festhalten könnte. Dies ist aber nicht möglich. Daher werden die Aussagen, für die dies auf einfache Weise möglich ist, formal in der Proklamation notiert, und alle anderen mit deutsch- oder englischsprachigen Sätzen in der Klausel. Eine Proklamation ist sozusagen der maschinenlesbare Teil einer Klausel.

Lemmadokumentationen

In der Dokumentation einer Proklamation finden wir manchmal auch noch Bestandteile, die eher Beiwerk sind, wie Beispiele oder Motivationen, aber die keine verbindlichen Aussagen darstellen. Sie gehören nicht mehr zu Klausel, aber sind Teil der Lemmadokumentation  (also der Dokumentation eines Symbols), welche die gesamte Dokumentation zu einem Symbol umfaßt.

Die Bezeichnung „Lemmadokumentation“ soll hier dazu dienen, den speziell zu einem bestimmte Lemma gehörenden Teil der Dokumentation von gesamten Dokumentation zu unterscheiden. Falls solch eine Unterscheidung aber nicht wichtig sein sollte oder falls schon dem Zusammenhang entnommen werden, was gemeint ist, kann man statt von einer „Lemmadokumentation“ auch einfach nur von „Dokumentation“ sprechen.

Die folgende Lemmadokumentation besteht aus der schon zuvor gezeigten Klausel und einer letzten Zeile, die eine eher vage Aussage enthält, die keine verbindliche Aussage über das Feld macht.

Lemmadokumentation zum Lemma »MaxValue« (beispielhaft)

public const int MaxValue
Der maximale Wert des Datentyps "int".
Dieses Feld ist oft nuetzlich!

Während Proklamationen prinzipiell auch von der Programmiersprache verstanden werden können (auch wenn wir hier noch nicht gelernt haben, wie das genau geht), sind Klauseln und Lemmadokumentation nur für Menschen verständlich, aber nicht für Computer.

Proklamationen sind in der Programmiersprache geschrieben, Klauseln und Dokumentationen in einer natürlichen Sprache, wie Deutsch oder Englisch.

Obwohl Proklamationen in der Programmiersprache geschrieben sind, werden wir erst später  lernen, wie man sie dort verwenden kann. Bis dahin sollten Proklamationen nicht  in Programme eingefügt werden!

Übungsaufgaben

/   ℯ

Entnehmen Sie der .NET-Framework -API-Dokumentation den Typ und die Bedeutung des Namens »global::System.Math.E«.

/   »TicksPerMillisecond«

Entnehmen Sie der .NET-Framework -API-Dokumentation den Typ und die Bedeutung des Namens »global::System.TimeSpan.TicksPerMillisecond«.

/   »METHODS_TO_SKIP«

Entnehmen Sie der .NET-Framework -API-Dokumentation den Typ und die Bedeutung des Namens »global::System.Diagnostics.StackTrace.METHODS_TO_SKIP«.