Parameter der Dokumentation in JavaScript 

Das in dieser Lektion vermittelte Verständnis von Parameterbeschreibungen aus der Dokumentation erschließt die Möglichkeit zum Nutzung einer Vielzahl vordefinierter Funktionen.

Beispiel einer Dokumentation

Entfernt man aus einem Aufrufausdruck den Argumentausdruck, so enthält man einen Rahmen mit einer Lücke, wie beispielsweise den Rahmen ≫Math.floor( … )≪ mit einer Lücke »…« in den runden Klammern. Solch eine Lücke an der Stelle eines entfernten Argumentausdrucks nennt man einen Para̲meter  (Substantiv mit Genus Maskulinum und Betonung auf der zweiten Silbe, die Linie unter dem zweiten „a“ kennzeichnet die Betonung). Ein Para̲meter drückt die Erwartung  eines Argumentes aus. Der Para̲meter kennzeichnet die Stelle, an welcher ein Argumentausdruck erwartet wird. Ein Para̲meter ist wie eine Lücke, die dann vom Argument gefüllt werden kann.

In der Dokumentation einer Funktion findet man eine oft Parameter mit einem Namen wie beispielsweise »x«.

Wir zeigen im folgenden die Dokumentation des Namens ≫Math.floor≪.

ECMAScript 2015 (vereinfacht und übersetzt)

Math.floor( x )

Ergibt den Boden (abgerundeten Wert) von »x«.

Am Anfang der Dokumentation findet sich eine Zeile mit dem Name der Funktion mit Klammern, die einen Parameternamen (wie »x«) enthalten können. Diese Zeile nennen wir die Kopfzeile  der Dokumentation der Funktion.

An den Klammern hinter dem Namen kann man erkennen, daß es sich um eine Funktion handelt.

Unter der Kopfzeile findet sich ein Text, der in einer natürlichen Sprache wie Englisch oder Deutsch verfaßt ist. Diesen Text nennen wir die Prosa  der Dokumentation der Funktion.

Para̲meternamen Damit man sich (beispielsweise in der Prosa) besser auf einen Para̲meter beziehen kann, hat ein Para̲meter einen Namen, den Para̲meternamen. Der Para̲metername ist eine Bezeichnung für einen Wert (wie beispielsweise eine Zahl), welcher dann erst durch die Angabe eines Argumentausdrucks konkret bestimmt wird. Ein Para̲metername hat jedoch für einen Aufruf einer Funktion sonst keine Bedeutung. Er erleichtert es nur, sich in der Dokumentation einer Funktion auf den Para̲meter zu beziehen. Der Parametername der obenstehenden Dokumentation lautet »x«.

Das Argument von ≫Math.floor≪

Die Anzahl der Parameter der Dokumentation drückt aus, mit wie vielen  Argumenten eine Funktion aufgerufen werden sollte.

Der Prosa kann oft entnommen werden, daß Argumentwerte eines bestimmten Typs  (Zahl oder Zeichenfolge) erwartet werden.

Die Dokumentation der Funktion ≫Math.floor≪ drückt beispielsweise aus, daß ein Argument erwartet wird, das eine Zahl darstellt, und daß der Wert des gesamten Aufrufausdrucks dann die Abrundung dieser Zahl darstellt.

Das heißt, beim Aufruf der Funktion sollte ein Ausdruck in die Klammern geschrieben werden, der eine Zahl darstellt.

Falls für das Argument ≫isNaN≪ zutrifft, ist das Ergebnis von ≫Math.floor≪ der Wert ≪NaN≫.

Auswertung

Math.floor( "abc" )

NaN

Math.floor( undefined )

NaN

Falls das Argument fehlt, so wird dies so interpretiert, als sei das Argument der Wert ≪undefined≫.

Auswertung

Math.floor()

NaN

Dieses Beispiel zeigt auf, weswegen es wichtig ist, zwischen Parametern  und Argumenten  zu unterscheiden. Die Funktion ≫Math.floor≪ hat laut ihrer Dokumentation einen  Parameter, aber sie wird in ≫Math.floor()≪ mit null  Argumenten aufgerufen.

Das folgende Beispielprogramm zeigt einen der Dokumentation der Funktion ≫Math.floor≪ entsprechenden Aufruf jener Funktion mit einem Argumentausdruck vom Typ »double«.

Auswertung

Math.floor( 2.7 )

2

⚠ Die Dokumentation einer Funktion erklärt dem Leser die Eigenschaften und die Bedeutung dieser Funktion. Sie ist nicht  dafür gedacht als ein JavaScript -Ausdruck verwendet zu werden. In der Dokumentation steht beispielsweise ≫Math.floor( x )≪, ein korrekter Aufruf dieser Funktion ist beispielsweise ≫Math.floor( 2.7 )≪. Der Para̲metername »x« aus der Dokumentation gehört also nicht  in den Quelltext.

Zeile aus einer Dokumentation

Math.floor( x )

möglicher Ausdruck

Math.floor( 2.7 )

Leere Para̲meterlisten

Wenn die Klammern hinter dem Funktionsnamen in der Dokumentation leer  sind, dann hat die dokumentierte Funktion keine Para̲meter, und sollte entsprechend auch mit leeren Klammern  (also ohne Argument ) aufgerufen werden.

Dokumentation von ≫Math.random()≪ in ECMAScript 2015  (gekürzt, übersetzt und überarbeitet)

Math.random( )

Ergibt eine Zufallszahl, die gleich 0 ist oder die größer als 0 und kleiner als 1 ist. Diese Funktion akzeptiert keine Argumente.

In der Dokumentation von ≫Math.random≪ findet man außerdem noch den Hinweis „Diese Funktion akzeptiert keine Argumente.

Wird doch ein Argumentausdruck angegeben, so hat dessen Wert keinen Einfluß auf den Wert des Aufrufs.

Auswertung

Math.random()

0.6460670353732043

Auswertung

Math.random( 1 )

0.2802523382776344

Auswertung

Math.random( "abc" )

0.4253523273659886

Auswertung

Math.random( undefined )

0.6838555845786954

An den Klammern hinter dem Namen ≫Math.random≪, die sich in der Dokumentation finden, kann man auch hier erkennen, daß es sich um eine Funktion handelt.

Para̲meter und Argumente

Para̲meternamen  und Argumentausdrücke  werden manchmal miteinander verwechselt : Para̲meternamen  finden sich in der Dokumentation  als Beschreibung einer Lücke, sie drücken das Fehlen  eines bestimmten Wertes aus, die Erwartung  eines Ausdrucks beim Aufruf im Quelltext. Argumentausdrücke  finden sich im Quelltext innerhalb mancher Ausdrücke und geben den zur Ermittlung des Para̲meterwerts zu nutzenden Ausdruck an, beispielsweise als ein Numerale oder als eine Summe. Da Para̲metername das Fehlen  eines Wertes ausdrücken und Argumentausdrücken einen Wert  ausdrücken, sind Argumentausdrücke  gewissermaßen das Gegenstück zu Para̲meternamen.

Weitere Beispiele für Funktionsdokumentationen

Hier zeigen wir die Dokumentation einiger der bisher schon vorgestellter Funktionen.

Das Verhalten dieser Funktionen bei Argumenten, die keine richtigen Zahlen darstellen oder fehlen, ist so wie schon oben für ≫Math.floor≪ beschrieben.

Dokumentation

Math.sqrt( x )

Ergibt die Quadratwurzel von »x«.

Dokumentation

Math.sin( x )

Ergibt den Sinus von »x«.

Dokumentation

parseFloat( string )

Wandelt das Numerale am Anfang von »string« in eine Zahl.

Der Name des Parameters deutet an, daß eine Zeichenfolge als Argument erwartet wird.

Übersicht

In der folgenden Übersicht steht »this« für das globale Verzeichnis.

Übersicht der Namen

 Name                        Art           Bedeutung
 this.Infinity               Zahl          Unendlich
 this.Math.PI                Zahl          die Kreiszahl Pi
 this.Math.abs               Funktion      Betrag
 this.Math.floor             Funktion      Boden
 this.Math.isNaN             Funktion      "ist NaN"
 this.Math.parseFloat        Funktion      Zahl eines Textes
 this.Math.random            Funktion      Zufallszahl
 this.Math.sin               Funktion      Sinus
 this.Math.sqrt              Funktion      Quadratwurzel
 this.undefined              Wert          "kein Wert"
 this.NaN                    Zahl          "keine Zahl"

Übungsfragen

?   Bedeutung von Ausdrücken

Ist (der Wert des Ausdrucks) ≫Math.abs( 2 )≪ eine Funktion?

?   Bedeutung von Ausdrücken (1)

Nennen Sie einen (weiteren) Ausdruck, dessen Wert eine Funktion ist!

?   Dokumentation lesen ⃗

Dokumentation einer Funktion mit einem Para̲meter (angelehnt an ECMAScript 2015)

Math.round( x )
Ergibt den gerundeten Wert von x.
Ergibt NaN, falls x nicht-echtzahlig ist.

Wir sagen, daß ein Wert x echtzahlig  ist, wenn der Wert von ≫isNan« gleich »false« ist, wenn man es mit diesem Wert x aufruft.

Fragen zum Verständnis der obigen Dokumentation

• Welchen eigentlichen Namen  hat die dokumentierte Funktion?
• Zu welchem Verzeichnis  gehört die Funktion?
• Welchen Namen hat der Para̲meter  der Funktion?

?   Ausdrücke lesen ⃗

Ist der Wert von ≫parseFloat( "2.7" )≪ eine eigentliche Zahl?

Ist der Wert von ≫Math.floor( parseFloat( "2.7" ))≪ eine eigentliche Zahl?

Wir sagen, daß ein Wert x echtzahlig  ist, wenn der Wert von ≫isNan« gleich »false« ist, wenn man es mit diesem Wert x aufruft.

?   Verständnis von Fachbegriffen ⃗

Zu einer (hypothetischen) Funktion »m« wird erklärt: „Die Funktion »m« ergibt den Wert 4.“. Welchen Wert hat dann »m( 3 )«?

Zu einer (hypothetischen) Funktion »f« wird erklärt: „Die Funktion »f« ergibt den Wert ihres Arguments.“. Welchen Wert hat dann »f( 3 )«?

Aus der freien Wildbahn

Wenn man im Quelltext einer Nachrichtenseite wie

Fragment

heise.de/-4603616

nach »random« sucht, findet man vermutlich einen Treffer (Stand 2019).

Bildung von Inkarnationen

Ein Plattenspieler kann erst nach der Verbindung mit einer Schallplatte Musik abspielen.

Ein Beispiel

.----------------------------------------.
| .----------------.     .------------.  | Eine Inkarnation einer Operation ist eine
| | Plattenspieler |<---( Schallplatte ) | Verbindung der Operation mit Daten, die
| '----------------'     '------------'  | dann ausgefuehrt werden kann.
'----------------------------------------'
                   |
                   V
              \          /
             - Interaktion -               Grundprinzipien:
              /          \                 1.) Verbindung zu startfaehiger Maschine
                   |                       2.) Start einer startfaehigen Maschine
                   V
                Ergebnis

Genau kann eine Funktion mit einem Parameter erst nach der Verbindung mit einem Argumentwert ausgeführt werden.

Inkarnation einer parametrisierten Funktion

  Inkarnation
.----------------------------------------.
| .----------------.     .------------.  | Inkarnation aus Funktion und Argumentwert
| | Funktion       |<---( Argumentwert ) |
| '----------------'     '------------'  |
'----------------------------------------'
                   |
                   V
              \          /
             - Ausführung -
              /          \
                   |
                   V
            Ergebnis/Wirkung

Übungsaufgaben

/   Aufrufe schreiben

Diese Übungsaufgabe soll das selbständige Schreiben von Aufrufen von Funktionen mit einem Para̲meter an Hand der Dokumentation üben.

Schreiben Sie einen Ausdruck für den Aufruf der Funktion ≫Math.sign≪ (welche Werte dabei genau verwendet werden, ist egal).

Dokumentation

Math.sign( x )

Ergibt das Vorzeichen von »x«.

Ergibt »+1«, falls »x« positiv ist.
Ergibt »-1«, falls »x« negativ ist.
Ergibt »+0«, falls »x« gleich »+0« ist.
Ergibt »-0«, falls »x« gleich »-0« ist.
Ergibt »NaN«, falls »x« nicht echtzahlig ist.

Wir sagen, daß ein Wert x echtzahlig  ist, wenn der Wert von ≫isNan« gleich »false« ist, wenn man es mit diesem Wert x aufruft.

/   Mathematische Aufrufe schreiben ⃗

Schreiben Sie möglichst kurze Ausdrücke, die den folgenden sprachlichen Bezeichnungen entsprechen, ohne dabei den Wert des Ausdrucks schon selber im Kopf auszurechnen! Die Werte der Ausdrücke sollten den mathematischen Werten der vorgegebenen Texte möglichst nahe kommen. (Passende Funktionen können im Verzeichnis ≫Math≪ gefunden werden.)

• Der Kosinus von Null
• Die Wurzel aus zwölf Prozent von Vierundsiebzig

Reserveaufgaben

/   Aufrufe schreiben (1)

(Diese Reserveaufgabe wird erst nach der Nachbesprechung der vorherigen Aufgabe bearbeitet, falls die vorherige Aufgabe noch nicht gelöst werden konnte.)

Schreiben Sie einen Ausdruck für den Aufruf der Funktion ≫Math.sqrt≪ (welche Werte dabei genau verwendet werden, ist egal).

Dokumentation

Math.sqrt( x )

Ergibt die Quadratwurzel von »x«.

Zusatzfragen *

?   Ausdrücke lesen *

Die folgenden Fragen sollen durch Lesen der Dokumentation beantwortet werden, nicht durch Ausprobieren (Starten von Programmen).

Welche Werte kann der Ausdruck ≫Math.floor( Math.random() * 3 )≪ haben?

Welche Werte kann der Ausdruck ≫Math.ceil( Math.random() * 3 )≪ haben?

Welche Werte kann der Ausdruck ≫Math.trunc( Math.random() * 3 )≪ haben?

Welche Werte kann der Ausdruck ≫Math.round( Math.random() * 3 )≪ haben?

Oben steht »Math« immer für den globalen Namen  ≫Math≪.

Zusatzaufgaben *

?   Runden *

Schreiben Sie einen Ausdruck für die Berechnung der auf zwei Nachkommastellen gerundeten Quadratwurzel von 10. Dabei soll die JavaScript -Implementation die Quadratwurzel berechnen und dann das Ergebnis auf zwei Nachkommastellen runden.

Zitate *

Das folgende Zitat soll die Verwendung der Begriffe “argument ” und “parameter ” in ECMAScript 2015 zeigen.

ECMAScript 2015

21.1.2.1 String.fromCharCode ( ...codeUnits )

The String.fromCharCode function may be called with any number of arguments which form the rest parameter codeUnits.