Dokumentation von Methoden in C♯

Das folgende Programm gibt die Kennung aus, unter der es läuft; es handelt sich dabei um eine ganze Zahl.

Program.cs

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

global::System.Console.Out

Wie Felder und Eigenschaften, so werden auch Methoden in C♯ dokumentiert.

Die Dokumentation der Methode »global::System.AppDomain.GetCurrentThreadId« findet man auf einer eigenen Web-Seite »msdn.microsoft.com/de-de/library/system.appdomain.getcurrentthreadid«.

Dokumentation von »global::System.AppDomain.GetCurrentThreadId« (gekürzt und vereinfacht)

Namensraum global::System 
Klasse AppDomain 
Methode
veraltet
Syntax:
public static int GetCurrentThreadId()
Ergibt die Kennung des laufenden Programmes.

Der enthaltende Typ einer Methode

Man kann der Dokumentation der Methode »GetCurrentThreadId« die Klasse entnehmen, zu welcher diese Methode gehört, nämlich »AppDomain«.

Der enthaltende Namensraum eines Typs

Man kann der Dokumentation den Namensraum entnehmen, zu welchem die Klasse, welche die Methode enthält, gehört, nämlich »System« (gemeint ist »global:System«).

Veraltete Methoden

Die Dokumentation enthält den Hinweise, daß diese Methode heute (2016) als veraltet erklärt wurde. Wir verwenden diese veraltete Methode hier in diesem Kurs aber trotzdem als Beispiel, weil sie so einfach aufzurufen ist.

Das 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.

Das Lemma

Das Lemma ist das, was dokumentiert wird.

Die Proklamation einer Methode

Unter einem Schaltwort verstehen wir hier ein Wort, das durch sein An- oder Abwesenheit Eigenschaften des Lemmas beschreibt.

Die Proklamation einer Dokumentation ist ein Teil der in formaler Weise durch einige Schaltwörter (wie »public« oder »static«) und auf ähnliche Weise Eigenschaften des Dokumentierten festlegt.

Beispielsweise ist das Lemma statisch, wenn in der Proklamation vor seiner Bezeichnung das Schaltwort »static« steht.

Die Proklamation wird von Microsoft manchmal auch Syntax genannt, jedoch entspricht diese Bezeichnung nicht der üblichen Bedeutung des Wortes „Syntax“ in der Informatik.

Die Proklamation lautet hier »public static int GetCurrentThreadId()«.

Wir lassen beim Zitieren der Dokumentation hier zur Vereinfachung das Wort „Syntax“ weg. Allgemein wird in diesem Kurs die Dokumentation oft im Vergleich zur Original-Dokumentation vereinfacht und übersetzt, ohne daß dies jedesmal ausdrücklich gekennzeichnet wird.

Proklamation von »global::System.AppDomain.GetCurrentThreadId«

public static int GetCurrentThreadId()

Das Wort »`public`«

Das Wort »public« bedeutet, daß der Eintrag der Klasse nicht versteckt ist. Ein versteckter Eintrag ist ein Eintrag einer Klasse, der von Klienten nicht ohne weiteres verwendet werden kann. Deswegen werden versteckte Einträge in der Dokumentation ohnehin auch normalerweise gar nicht angezeigt. Daher ist es auch oft überflüssig, das Wort »public« anzuzeigen, weil es in der Dokumentation normalerweise ohnehin selbstverständlich ist, daß alle Lemmata »public« sind. Deswegen können wir das Wort »public« in der Dokumentation bis auf weiteres ignorieren.

Das Wort »`static`«

Das Wort »static« bedeutet, daß man die beschriebene Methode statisch ist, also daß man sie aufrufen kann, ohne daß man dafür ein Objekt benötigt. (Objekte werden in diesem Kurs erst später behandelt werden.)

Der Rückgabetyp (hier: »`int`«)

In der Dokumentation der Methode »GetCurrentThreadId« steht der Typ des Aufrufs, nämlich »int«, vor dem einfachen Namen der Methode.

Proklamation von »GetCurrentThreadId«

public static int GetCurrentThreadId()

Die Angabe »int« vor dem einfachen Namen »GetCurrentThreadId« besagt, daß ein Aufrufausdruck dieser Methode, also der Ausdruck »global::System.AppDomain.GetCurrentThreadId()« den Typ »int« hat.

Der Rückgabetyp ist der Typ des Aufrufs einer Methode. Er findet sich in der Dokumentation direkt vor dem eigentlichen Namen der Methode.

Eine Methode, deren Aufruf den Typ »int« hat, wird auch als eine „int-Methode“ bezeichnet. Dabei kann diese Art von Bezeichnung auch mit anderen Datentypen verwendet werden. Der Aufruf einer „double-Methode“ hat also den Typ »double«, und so weiter. Genauso ist aber auch eine Präfigierung mit anderen Eigenschaften möglich, so kann man auch von einer „AppDomain-Methode“ sprechen, um auszudrücken, daß die Methode zur Klasse »global::System.AppDomain« gehört, und so weiter.

Wir schreiben bis auf weiteres Typen (wie »int«) nicht in den Quelltext. Die Typen dienen uns hier lediglich zur Beschreibung von Methoden.

Das Lemma einer Methode (hier: »`GetCurrentThreadId()`«)

Hinter »int« folgt in der Proklamation eine Art von Muster des Aufrufausdrucks, nämlich »GetCurrentThreadId()«.

Während Lemmata von Feldern oder Eigenschaften, wie »MaxValue«, Bezeichner sind, enthalten Lemmata von Methoden, wie »GetCurrentThreadId()«, noch ein Klammerpaar.

Dieses Klammerpaar erlaubt es, Methodenlemmata von Feld- oder Eigenschaftenlemmata zu unterscheiden, aber es ist leider etwas mißverständlich, da es mit einem Aufruf der Methode verwechselt werden kann. Man muß es leider jeweils aus dem Zusammenhang entnehmen, ob mit »GetCurrentThreadId()« das Lemma der Methode (also praktisch die Methode selber, da das Lemma für die Methode steht) oder ein Aufruf der Methode (also praktisch das Ergebnis des Aufrufes) gemeint ist.

Das Lemma »GetCurrentThreadId()« identifiziert also eindeutig eine bestimmte Methode, wenn die Klasse »global::System.AppDomain« schon vorgegeben ist, so wie das Lemma »MaxValue« ein bestimmtes Feld der Klasse »global::System.Int32« bestimmt.

Im Vergleich zum eigentlichen Namen der Methode enthält das Lemma also noch ein Paar von Klammern.

Allgemein identifiziert ein Lemma einen bestimmten Eintrag einer Klasse, wenn die Klasse schon gegeben ist. Lemmata ohne Klammern stehen für Felder oder Eigenschaften, Lemmata mit Klammern für Methoden.

Wir werden in diesem Kurs ab jetzt Methoden meist nicht mehr mit ihrem Namen (wie beispielsweise »GetCurrentThreadId«) angeben, sondern mit ihrem Lemma (wie beispielsweise »GetCurrentThreadId()«). In der Regel steht davor ein Wort wie „Methode“, wenn die Methode damit gemeint ist, oder eine Wort wie „Aufrufausdruck“, wenn der Aufrufausdruck gemeint ist. Wir sprechen also beispielsweise von „der Methode »GetCurrentThreadId()«“ oder „dem Aufruf »GetCurrentThreadId()«“; im ersten Fall ist die Methode selber damit gemeint, im zweiten Fall der Ausdruck, mit dem die Methode aufgerufen wird.

Wir verwenden auch manchmal die Hintereinanderschreibung von Klasse und Lemma, um einen Eintrag einer Klasse eindeutig zu identifizieren, wie beispielsweise »global::System.AppDomain.GetCurrentThreadId()« (bestehend aus der Klasse »global::System.AppDomain«, einem Punkt ».« und dem Lemma »GetCurrentThreadId()«).

Lemma von »global::System.AppDomain.GetCurrentThreadId«

GetCurrentThreadId()

Die Verwendung eines Lemmas

Unter der Verwendung eines Lemmas verstehen wir

bei einem Felde oder Eigenschaft das Vorkommen des Names des Feldes beziehungsweise der Eigenschaft als Ausdruck in einem Programm, also das Auslesen des Wertes des Feldes beziehungsweise der Eigenschaft und
bei einer Methode den Aufruf der Methode in einem Programm.

Die Klausel

Schließlich findet man in der Dokumentation eine Beschreibung des Wertes, den der zugehörige Aufrufvorgang ergibt. Diese bildet zusammen mit der Proklamation die Klausel.

Klausel von »global::System.AppDomain.GetCurrentThreadId«

public static int GetCurrentThreadId()

Ergibt die Kennung des laufenden Programmes.

Methoden und Felder oder Eigenschaften

Vor den Methoden haben wir schon die ebenfalls dokumentierten Wertnamen (Felder oder Eigenschaften) kennengelernt. Ein Methodenname ist kein Wertname und umgekehrt. Ob ein Name der Name einer Methode, wie »global::System.AppDomain.GetCurrentThreadId«. oder eines Feldes, wie »global::System.Int32.MaxValue«, oder einer Eigenschaft, wie »global::System.Console.Title«, ist, kann der Dokumentation entnommen werden.

Die Beispiele in diesem Kapitel

In diesem Kapitel werden einige Methoden als Beispiele für Methoden vorgestellt. Die gewählten Beispiel wurden als Beispiel ausgewählt, weil sie relativ einfach verwendbar sind, aber nicht unbedigt, weil sie immer besonders nützlich sind. Deswegen wäre es in diesem Kapitel Zeitverschwendung, wenn man zu sehr versuchen würde, Details der hier als Beispiel vorgestellten Methoden zu erfahren und zu verstehen.

Es geht in diesem Kapitel nicht um die speziellen als Beispiel ausgewählten Methoden, sondern darum allgemein zu verstehen, wie Methoden verstanden und verwendet werden.

Die Dokumentation der Methode »`global::Microsoft.JScript.MathObject.random()`«

»msdn.microsoft.com/library/microsoft.jscript.mathobject.random« (überarbeitet und übersetzt)

MathObject.random-Methode ()

Bibliothek: .NET 4.6 and 4.5

Diese Methode unterstützt Produktinfrastruktur und ist nicht für direkte Aufrufe gedacht.

Erzeugt eine Zufallszahl zwischen Null und Eins.

Namensraum: »Microsoft.JScript«

Bau: »Microsoft.JScript« (in »Microsoft.JScript.dll«)

Syntax

public static double random()

Ergebnis

Typ: »System.Double«

Eine Zahl, die entweder Null oder größer als Null und kleiner als Eins ist.

Lemma von »msdn.microsoft.com/library/microsoft.jscript.mathobject.random«

random()

Proklamation von »msdn.microsoft.com/library/microsoft.jscript.mathobject.random«

public static double random()

Klausel von »msdn.microsoft.com/library/microsoft.jscript.mathobject.random«

public static double random()

Ergibt eine Zahl, die entweder Null oder größer als Null und kleiner als Eins ist.

Wir entnehmen einer Anmerkung in der Dokumentation der Methode »global::Microsoft.JScript.MathObject.random()«, daß sie „nicht für direkte Aufrufe gedacht“ ist. Jene Methode wird in diesem Kurs aber trotzdem verwendet, weil sie als einfaches Beispiel einer einfachen Methode besonders gut geeignet ist.

Nicht aus der Dokumentation kopieren!

Ein Programmierer muß Dokumentationen von Methode verstehen, um dann die daraus gewonnenen Informationen zum Schreiben von Programmen verwenden zu können. Ein gelegentlicher Fehler von Anfängern, welche die Dokumentation noch nicht richtig verstehen, ist es, die Dokumentation einer Methode in ein Programm zu kopieren. Das ist in der Regel verkehrt.

Nicht aus der Dokumentation in den Quelltext kopieren!

Der folgende Text zeigt, wie es aussehen kann, wenn ein Anfänger eine Proklamation (in der Dokumentation auch „Syntax“ genannt) in sein Programm kopiert, wie dies öfter beobachtet wurde. Anfänger, die so vorgehen sind danach meist nicht in der Lage, das entstandene Programm noch selbständig zu korrigieren. Daher sollte es grundsätzlich vermieden werden, eine Proklamation in den Quelltext zu kopieren.

Text

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

Konsole (übersetzt)

Text(4,7): Fehler CS1513: } erwartet
Text(4,46): Fehler CS1002: ; erwartet
Text(4,50): Fehler CS1022: Typ oder Namensraumdefinition, oder Dateiende erwartet

Schon zuvor wurde ja ein Programmbeispiel vorgestellt, das zeigt, wie die Methode »global::System.AppDomain.GetCurrentThreadId()« richtig aufgerufen wird. Wenn man sich das Programmieren durch Kopieren aus einer Vorlage erleichtern will, dann sollte man ein solches Beispielprogramm kopieren, aber nichts aus der Dokumentation!

Die Dokumentation in IDEs

Auch einzelne IDEs enthalten Kopien aus der Dokumentation. Wir behandeln hier die Webseiten mit der Dokumentation, da die Dokumentation auf den Webseiten die offizielle Hauptquelle für die Dokumentation darstellt.

Neue URI für Dokumentation

Seit 2018 wird die Dokumentation auch unter eine neuen URI angeboten.

Neue URI

https://docs.microsoft.com/dotnet/api/?view=netframework-4.7.2

Übungsfragen

⚠ Da die Auswahl an einfach aufrufbaren Methoden an dieser Stelle des Kurses noch nicht so groß ist, werden in den Übungsaufgaben dieser und den folgenden Lektionen einige Methoden als Beispiele verwendet, deren Sinn (Nutzen) nicht immer gut erkennbar ist. Der Leser sollte sich an dieser Stelle noch keine Gedanken darüber machen, wofür diese Methoden gut sind ! Es geht zunächst nur darum, an (beliebigen) Beispielen zu erlernen, wie Methoden aufgerufen werden.

(Da es nicht möglich war, einfache und offensichtlich nützliche Methoden zu finden, haben wir hier der Einfachheit den Vorrang vor der erkennbaren Nützlichkeit gegeben. Die Methoden in dieser Übung sind also relativ einfach aufzurufen, aber ihr Nutzen ist derzeit oft nicht erkennbar.)

Im folgenden findet sich die Dokumentation einer Methode der .NET -Bibliothek.

Dokumentation von »global::System.IO.Directory.GetCurrentDirectory« (vereinfacht und übersetzt)

Namensraum global::System.IO 
Klasse Directory 
Methode
public static string GetCurrentDirectory()
Aktuelles Arbeitsverzeichnis

⚠ Denken Sie jetzt nicht weiter über die Bedeutung des Begriffs „Aktuelles Arbeitsverzeichnis“ nach! Die Methode »GetCurrentDirectory()« dient hier nur als ein Beispiel, aber ihre genaue Bedeutung ist hier nicht wichtig.

? Lesen von Dokumentation

Welchen Typ hat ein Aufruf der eben beschriebenen Methode »GetCurrentDirectory()«?

Zu welcher Klasse gehört die oben dokumentierte Methode »GetCurrentDirectory()«?

Zu welchem Namensraum gehört diese Klasse?

? Selbständiges Lesen von Dokumentation

Welchen Typ hat ein Aufruf der Methode »global::System.Console.ReadLine()«?

? Selbständiges Lesen von Dokumentation (1)

Welchen Typ hat ein Aufruf der Methode »global::System.Console.Read()«?

Übungsaufgaben

Bei der Bearbeitung dieser Übungsaufgaben sollten die folgenden Hinweise beachtet werden:

Kopieren Sie nichts aus der Dokumentation in Ihr Programm.
Verändern Sie nichts am fest vorgegebenen Ausdruckrahmen.

/ Selbständiges Schreiben von Programmen

Schreiben Sie ein C♯ -Programm, welches das Ergebnis eines Aufrufs der in einer voranstehenden Übungsfrage behandelten Methode »GetCurrentDirectory()« ausgibt.

Um diese Aufgabe zu lösen, kann wie folgt vorgegangen werden:

Das obige Beispielprogramm »Program.cs« kopieren.
Den darin vorkommenden Methodenaufruf »global::System.AppDomain.GetCurrentThreadId()« ändern.

Wenn diese Aufgabe richtig gelöst wurde, dann sollte beim Übersetzen und beim Ablauf des Programms keine Fehlermeldung erscheinen, und das Programm sollte einen Verzeichnispfad (einen Text) ausgeben.

Reserveaufgaben

/ Selbständiges Arbeiten mit der Dokumentation

Schreiben Sie ein C♯ -Programm, welches das Ergebnis eines Aufrufs der Methode »global::System.Threading.Thread.GetDomainID()« ausgibt.

/ Selbständiges Arbeiten mit der Dokumentation (1)

Schreiben Sie ein C♯ -Programm, welches das Ergebnis eines Aufrufs der Methode »global::System.Runtime.InteropServices.RuntimeEnvironment.GetRuntimeDirectory()« ausgibt.

/ Selbständiges Arbeiten mit der Dokumentation (2)

Schreiben Sie ein C♯ -Programm, welches das Ergebnis eines Aufrufs der Methode »global::System.Runtime.InteropServices.Marshal.GetLastWin32Error()« ausgibt.

Begriffe *

„Rückgabetyp“ *

„Rückgabetyp“ (Deutsch)

Englisch “return type ”

Quelle Dieser Begriff wird in der Informatik weithin verwendet. Eine Suchmaschine zeigt beispielsweise viele einschlägige Treffer für die Eingabe [Rückgabetyp] an.

Stand 2016

“return type” (English)

German „Rückgabetyp“

source C# Language Specification, Version 5.0; 10.6 Methods

Reviewed 2016