Wie interpretiere ich Funktionsparameter der API-Dokumentation?

Gibt es einen Standard zur Interpretation der Syntax von Funktionsschnittstellen in API-Dokumentationen und wenn ja, wie ist dieser definiert?

Hier ist ein Beispiel zum Ändern der Farbe eines Elements im JavaScript-Skripthandbuch für Photoshop für die Funktion "fillColor":

fillPath
([fillColor]
[, mode]
[, opacity]
[, preserveTransparency] [, feather]
[, wholePath] [, antiAlias])

Was bedeuten die Klammern und warum stehen in den Klammern Kommas? In welcher Beziehung steht dies zu den folgenden Beispielaufrufen?

myPath.fillPath(myNewColor)

myPath.fillPath(mynewColor, {
    mode: RGB,
    opacity: .5
})

Warum ist die API-Dokumentation so geschrieben, dass mehrjährige Neulinge / Hacker / Heimwerker wie ich verwirrt werden?

Es ist wirklich nicht so geschrieben. Ich bin damit einverstanden, dass es in API-Dokumentationen keine Benutzerfreundlichkeit zu geben scheint. Es gibt jedoch viele Übergänge von Syntaxkonventionen älterer manStile zu modernen API / Namespace-Konventionen.

In der Regel hat der Typ der Person, die mit API arbeitet, einen Hintergrund in der Entwicklung oder zumindest einen "Hauptbenutzer". Diese Benutzertypen sind an solche Syntaxkonventionen gewöhnt, und es ist sinnvoller, dem API-Dokument zu folgen, als zu versuchen, neue zu erstellen.

Gibt es irgendwo ein mysteriöses Dokument, das den Leuten sagt, wie man API-Dokumentation liest?

Es gibt wirklich keinen Standard- oder RFC-Supersekretsyntaxdoc, der irgendwo herumliegt, jedoch gibt es eine ~ 30 Jahre alte Datei für das UNIX- Manpage-Synposis-Format, die weit verbreitet ist.

Einige Beispiele hierfür (und die Beantwortung Ihrer Frage) wären:

Unterstrichene Wörter gelten als Literale und werden so eingegeben, wie sie erscheinen.

Eckige Klammern ([]) um ein Argument geben an, dass das Argument optional ist.

Ellipsen ... werden verwendet, um zu zeigen, dass der vorherige Argument-Prototyp wiederholt werden kann.

Ein Argument, das mit einem Minuszeichen beginnt, wird oft als eine Art Flag-Argument verstanden, selbst wenn es an einer Stelle erscheint, an der ein Dateiname erscheinen könnte.

Fast alle programmierbezogenen Dokumentationen verwenden diese Art von Syntaxkonvention , von Python , Manpages , Javascript- Bibliotheken ( Highcharts ) usw.

Aufschlüsselung Ihres Beispiels aus der Adobe-API

fillPath
([fillColor]
[, mode]
[, opacity]
[, preserveTransparency] [, feather]
[, wholePath] [, antiAlias])

Wir sehen, dass fillPath()(eine Funktion) optionale Argumente fillColor, mode, opacity, preserveTransparency, feathe, wholePathoder antiAlias. Beim Aufrufen fillPath()können Sie einen beliebigen Parameter an alle übergeben. Die Kommas innerhalb des optionalen Zeichens []bedeuten, dass Sie, wenn dieser Parameter zusätzlich zu anderen verwendet wird, das Komma benötigen, um ihn zu trennen. (Der gesunde Menschenverstand braucht manchmal sicher, aber manchmal benötigen einige Sprachen wie VB explizit diese Kommas, um richtig zu definieren, welcher Parameter fehlt!). Da Sie keinen Link zur Dokumentation erstellt haben (und ich ihn auf der Skriptseite von Adobe nicht finden kann), können Sie nicht feststellen , welches Format die Adobe-API erwartet. Am Anfang der meisten Dokumentation sollte jedoch eine Erklärung stehen, in der die darin verwendeten Konventionen erläutert werden.

Diese Funktion könnte also wahrscheinlich auf viele Arten verwendet werden:

fillPath() //Nothing passed
fillPath(#000000,RGB) // Black, in RGB mode
fillPath(#000000,RGB,50) // Black, in RGB mode, half opacity

//Now it gets tricky, this might ALSO be acceptable:
fillPath(#000000,50) // Black, no mode, half opacity

//OR
fillPath(#000000,,50) // Black, no mode, half opacity

Auch hier gibt es normalerweise einige Standards für alle Dokumentationen in Bezug auf API / Programmierung. In jedem Dokument kann es jedoch zu geringfügigen Unterschieden kommen. Als Hauptbenutzer oder Entwickler wird von Ihnen erwartet, dass Sie die Dokumente / Frameworks / Bibliotheken lesen und verstehen können, die Sie verwenden möchten.

API-Dokumente für dynamisch typisierte Sprachen können nicht sehr aussagekräftig sein, wenn sie nicht sorgfältig geschrieben werden. Fühlen Sie sich also nicht schlecht, selbst der erfahrenste Entwickler kann es schwer haben, sie zu verstehen.

Über Klammern und dergleichen gibt es normalerweise einen Abschnitt mit Codekonventionen, in dem die genaue Verwendung außerhalb von Literalbeispielen erläutert wird. Obwohl EBNF- , Regex- und Eisenbahndiagramme fast allgegenwärtig sind, sollten Sie mit ihnen vertraut sein, um die meisten Notationen zu verstehen.

Die Klammern bedeuten, dass die Eigenschaft optional ist. Beachten Sie jedoch, dass Sie, wenn Sie eine Eigenschaft auf den n-ten Rang setzen möchten, entweder Eigenschaften für die führende Eigenschaft deklarieren oder sie als undefiniert deklarieren müssen:

fillPath() //good
fillPath ( someFillColor ) //good
fillPath ( someFillColor, mode ) //good
fillPath ( undefined, mode ) //good
fillPath ( mode ) //bad
fillPath ( undefined ) //really bad

Ich hatte vor einiger Zeit dieselbe Frage und jemand hat mich auf die erweiterte Backus-Naur-Form hingewiesen .

Dies ist sinnvoll, da mit der Programmierung potenziell unbegrenzte Ergebnisse erzielt werden können. Die Dokumentation kann nicht für jeden möglichen Fall ein Beispiel anzeigen. Ein gutes Beispiel für die allgemeine Verwendung ist hilfreich, aber sobald Sie die zugrunde liegende Syntax gelesen haben, können Sie Ihren eigenen Code erstellen.