Dokumentation von Funktionen in VBA

Die folgende Eingabe gibt eine mehr oder weniger zufällig ausgewählte Zahl zwischen 0 (einschließlich) und 1 (ausschließlich) aus.

Direktbereich

? VBA.Math.Rnd()

 0.7055475 

Dokumentation im Handbuch („Hilfe“)

Die Dokumentation des Bezeichners »Rnd« kann über das VBA-Handbuch oder das Web gefunden werden, dazu wird in der VBA-Hilfe nach »Rnd« gesucht oder im Direktbereich bei in »Rnd« positionierter Schreibmarke die Taste F1 oder Strg-F1 gedrückt. Der genaue Weg zum Finden der Dokumentation unterscheidet sich von einer Office-Version zur anderen und kann daher hier nicht ganz detailliert beschrieben werden. Es sollte eine Seite gefunden werden, die »Rnd« im Titel enthält und eine Abschnitt »Syntax« hat, bei einigen deutschen Office-Versionen ist diese Seite auch in deutscher Sprache verfaßt.

Falls F1 einmal nicht zur richtigen Handbuchseite führen sollte, kann die richtige Handbuchseite auch im Inhaltsverzeichnis des Handbuchs gesucht werden.

Dokumentation im Web

Alternativ kann auch im Web nach »"VBA" "Rnd"« oder »"VBA" "MSDN" "Rnd"« gesucht werden. Um die maßgeblich, offizielle Dokumentation von Microsoft  zu finden, sollten dann unter den Suchergebnisse nur Seiten beachtet werden, die auch von Microsoft  stammen. Außerdem ist direkt nach der ersten Anzeige einer solchen Seite zunächst zu überprüfen, ob sie auch wirklich die Dokumentation von »Rnd« für die Programmiersprache „VBA“ und nicht etwa für andere Programmiersprache mit ähnlich klingenden Namen, wie „VB“, angezeigt wird. Im besten Fall findet man eine Seite auf deutsch und genau die verwendete Version von VBA.

Bei einem Test im Jahre 2014 wurde beobachtet, daß bei Microsoft zwar eine englischsprachige Web-Dokumentationsseite zu »Rnd« gefunden wurde, aber keine deutschsprachige (obwohl eine deutschsprachige Dokumentationsseite zu »Rnd« im Handbuch einiger Office -Versionen existiert). Die englischsprachige Dokumentationsseite (URI »http://msdn.microsoft.com/en-us/library/office/gg251628(v=office.15).aspx«) kann daran erkannt werden, daß sie am Anfang den Satz “Returns a Single containing a random number.” enthält, die deutschsprachige enthält an seiner Stelle: „Gibt einen Wert vom Typ Single zurück, der eine Zufallszahl darstellt.“.

Auf der englischsprachigen Web-Dokumentationsseite findet man 2014 den Hinweis „Gilt für: Office 2013 | VBA“ (englisch: “Applies to: Office 2013 | VBA ”), dieser Hinweis zeigt deutlich an, daß man die Dokumentationsseite für die richtige Sprache, nämlich VBA, gefunden hat. Man kann daran auch überprüfen, ob die Dokumentationsseite auch für die verwendete Office -Version gilt. Es ist aber im Fall von VBA meist nicht so schlimm, wenn die Dokumentationsseite zu einer anderen Office -Version gehört, da die grundlegenden Funktionen von VBA sich im Laufe der Zeit meist nicht verändert haben. Die genaue Office -Version hat hauptsächlich bei Funktionen eine Bedeutung, welche sich auf Bestandteile von Office -Programmen beziehen, die sich im Laufe der Zeit verändert haben.

Jenen Hinweise kann man auch verwenden, um die richtige Seite zu finden, indem man mit einer Suchmaschine nach einem wörtlichen Vorkommen jenes Hinweises zusammen mit dem Namen, zu dem man Informationen sucht, sucht.

Verstehen der Dokumentation

Wir geben hier Auszüge aus einer Original-Dokumentation der Funktion »Rnd« wieder. Die Dokumentation dieser Funktion bei der vom Leser genutzten Office-Version kann sich aber davon unterscheiden! Dennoch sollten die wesentlichen Schreibweisen und Aussagen der Dokumentation der Funktion »Rnd« den hier wiedergegebenen ähneln.

Wir geben hier eine Variante der Dokumentation wieder, die nicht ganz korrekt ist, weil sie zur Vereinfachung und Anpassung an diesen Kurs etwas verändert wurde. Einige Teile der Original-Dokumentation sind nämlich an dieser Stelle des Kurses noch nicht verständlich. Die korrekt Original-Dokumentation kann der daran interessierte Leser ja bei Bedarf selber nachlesen.

Dokumentation von »VBA.Math.Rnd« (vereinfacht, verändert und verkürzt)

Rnd-Funktion

Gibt eine Zufallszahl vom Typ Double zurück.

Proklamation („Syntax“)

Rnd()

Prosa

Bei jedem Aufruf wird eine Zahl, die kleiner als 1 und größer als 0 oder gleich 0 ist, zurückgegeben.

Bei mehreren direkt aufeinanderfolgenden Aufrufen wird in der Regel jeweils eine andere Zahl zurückgegeben, so daß die nach vielen Aufrufen erhaltene Liste von Zahlen aus Zahlen besteht, die meist ungefähr gleichmäßig im Bereich zwischen 0 und 1 verteilt sind.

Unter der Proklamation  verstehen wir den formalen Teil am Anfang der Dokumentation, wie er auch im Objektkatalog zu finden ist.

Die Prosa  ist die deutsch- oder englischsprachige Erklärung zu einer Funktion.

Die Aussage „Gibt einen Wert vom Typ Double zurück“ besagt, daß ein Aufrufausdruck dieser Funktion, also der Ausdruck »VBA.Math.Rnd« den Typ »Double« hat. Dieser Typ des Aufrufausdrucks einer Funktion wird auch „Rückgabetyp“ bezeichnet.

Funktionen, die wie »VBA.Math.Rnd« einen Aufrufausdruck vom Datentyp »Double« haben, bezeichnet man manchmal auch als „eine Double -Funktion“ und entsprechend Funktionen anderer Datentypen mit dem jeweiligen Datentyp ihres Aufrufausdrucks.

Der Rückgabetyp einer Funktion ist der Typ des Aufrufs einer Funktion.

Die letzte Zeile dieser Dokumentation legt fest, daß der Wert eines Aufrufs stets größer als 0.0 oder gleich 0.0 und kleiner als 1.0, aber nicht 1.0 ist.

Unter der Überschrift „Syntax“ folgt eine Art von von Muster des Aufrufausdrucks »Rnd()«, welcher in Zusammenhang mit VBA auch als Syntax bezeichnet wird. Wir nennen diese Syntax auch manchmal Proklamation.

Die Dokumentation des Rückgabetyps

Der Rückgabewert erscheint in der Dokumentation einer Funktion manchmal hinter der runden Klammer zu mit »As«. Manchmal wird er auch nicht angezeigt und muß dann dem Zusammenhang oder anderen Quellen entnommen oder auf anderen Wegen ermittelt werden. Falls kein fester Rückgabetyp angegeben wird, so ist es auch möglich, daß der Rückgabetyp bei verschiedenen Aufrufen der Funktion unterschiedlich sein könnte (je nach dem zurückgegebenen Wert).

Proklamation einer hypothetischen Funktion »f« mit  Angabe des Rückgabetyps »Double«

Function f() As Double

Proklamation einer hypothetischen Funktion »f« ohne  Angabe des Rückgabetyps

Function f()

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

Die Syntax-Anzeige

Strg-i führt normalweise zur Anzeige der Syntax einer Funktion, wenn die Schreibmarke auf oder direkt hinter dem Namen der Funktion steht.

⇑-Strg-i führt normalweise zur Anzeige der Syntax einer Funktion, wenn die Schreibmarke in den Klammern eines Funktionsaufrufs steht.

An dieser Stelle des Kurses wurden noch nicht alle Teile der Original-Syntax der Funktion »Rnd« erklärt, einige dieser Teile werden aber in späteren Lektionen noch erklärt werden.

Der Objektkatalog

F2 ruft den Objektkatalog ohne Bezug zum Bezeichner unter der Schreibmarke auf.

⇑-F2 ruft den Objektkatalog für den Bezeichner unter der Schreibmarke auf.

Wir sehen den Objektkatalog hier ebenfalls als eine Teil der Dokumentation an.

Er enthält noch die Information, daß die Funktion »Rnd« zum Modul »Math« gehört und daß dieses Modul wiederum zur Bibliothek »VBA« gehört. Im Objektkatalog werden Module auch als Klassen bezeichnet.

Man kann die Funktion »VBA.Math.Rnd« auch als „eine VBA.Math -Funktion“ bezeichnen, weil sie im Modul »VBA.Math« enthalten ist.

Im Objektkatalog erscheint die „Syntax“ oft in englischer Sprache.

Wenn ein Eintrag im Objektkatalog angezeigt wird, so kann man mit F1 oft zur Dokumentation dieses Eintrags gelangen.

Übungsfragen

⚠ Da die Auswahl an einfach aufrufbaren  Funktionen an dieser Stelle des Kurses noch nicht so groß ist, werden in den Übungsaufgaben dieser und den folgenden Lektionen einige Funktionen 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 Funktionen gut sind ! Es geht zunächst nur darum, an (beliebigen) Beispielen zu erlernen, wie Funktionen aufgerufen werden.

Im folgenden findet sich die vereinfachte Dokumentation einer Funktion der Standardbibliothek. In der folgenden überarbeiteten und vereinfachten Dokumentation sind Informationen aus dem VBA-Objektkatalog und dem VBA-Handbuch zusammengefaßt.

Dokumentation von »VBA.FileSystem.CurDir$« (überarbeitet und vereinfacht)

Bibliothek »VBA«

Modul »FileSystem«

CurDir$-Funktion

Gibt einen Wert vom Typ String zurück, der den aktuellen Pfad darstellt.

Syntax

CurDir$()

⚠ Denken Sie jetzt nicht weiter über die Bedeutung von „aktueller Pfad“ nach! Die Funktion »CurDir$« 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 Funktion »VBA.FileSystem.CurDir$«?

?   Selbständiges Lesen von Dokumentation

Welchen Typ  hat ein Aufruf der Funktion »VBA.FileSystem.FreeFile«?

Übungsaufgaben

/   Selbständiges Schreiben von Programmen

Schreiben Sie eine VBA-Eingabe (beginnend mit einem Fragezeichen »?«), welche das Ergebnis eines Aufrufs der in einer voranstehenden Übungsfrage behandelten Funktion »VBA.FileSystem.CurDir$« ausgibt.

Reserveaufgaben

/   Selbständiges Arbeiten mit der Dokumentation

Schreiben Sie eine VBA-Eingabe (beginnend mit einem Fragezeichen »?«), welche das Ergebnis eines Aufrufs der Funktion »VBA.FileSystem.FreeFile« ausgibt.

/   Selbständiges Arbeiten mit der Dokumentation (1)

Schreiben Sie ein VBA-Programm, welches das Ergebnis eines Aufrufs der Funktion »VBA.Conversion.Error$« ausgibt.