Wie sind Funktionsparameter in der Software- und Sprachdokumentation zu interpretieren?

Question

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

Hier ist ein Beispiel dafür, wie man die Farbe eines Elements ändern kann, das JavaScript-Skript-Handbuch für Photoshop für die Funktion "fillColor":

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

Welche Bedeutung haben die Klammern und warum stehen in den Klammern Kommas? In welchem Zusammenhang steht dies mit den folgenden Beispielanrufen?

myPath.fillPath(myNewColor)

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

Answer 1

Warum also ist die API-Dokumentation so verfasst, dass sie Neulinge / Hacker / Heimwerker wie mich verwirrt?

So sollte es eigentlich nicht geschrieben werden. Ich stimme zu, dass es in den API-Dokumentationen keine Benutzerfreundlichkeit zu geben scheint. Allerdings gibt es eine Menge Überschneidungen mit älteren man Syntaxkonventionen an die modernen API/Namespace-Konventionen angepasst.

In der Regel hat die Person, die mit API arbeitet, einen gewissen Hintergrund in der Entwicklung oder ist zumindest ein "Power-User". Diese Art von Benutzern ist an solche Syntaxkonventionen gewöhnt und es ist sinnvoller, sich an das API-Dokument zu halten, als zu versuchen, neue zu erstellen.

Gibt es irgendwo ein geheimnisvolles Dokument, das den Leuten erklärt, wie man die API-Dokumentation liest?

Es gibt wirklich keinen Standard oder RFC, supersekretsyntaxdoc, der irgendwo herumliegt, aber es gibt eine ~30 Jahre alte Datei für UNIX man page synposis format die weit verbreitet ist.

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

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

Eckige Klammern ( [] ) um ein Argument zeigen 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, auch wenn es an einer Stelle erscheint, an der ein Dateiname stehen könnte.

Fast die gesamte programmierbezogene Dokumentation verwendet diese Art von Syntaxkonvention, von Python , Handbuchseiten , Javascript-Libs ( Highcharts ), usw.

---

Aufschlüsselung des Beispiels aus der Adobe-API

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

Wir sehen, dass fillPath() (eine Funktion) nimmt optionale Argumente fillColor, mode, opacity, preserveTransparency, feathe, wholePath o antiAlias . Aufruf von fillPath() können Sie jeden dieser Parameter übergeben, von keinem bis zu allen. Die Kommas innerhalb der optionalen [] bedeutet, dass Sie, wenn dieser Parameter zusätzlich zu anderen verwendet wird, das Komma als Trennzeichen benötigen. (Gesunder Menschenverstand manchmal, sicher, aber manchmal brauchen einige Sprachen wie VB, ausdrücklich diese Kommas, um richtig abzugrenzen, welcher Parameter fehlt!). Da Sie nicht auf die Dokumentation verwiesen haben (und ich kann sie auch nicht auf Adobes Skripting-Seite ) gibt es keine Möglichkeit zu erfahren, welches Format die Adobe-API erwartet. Es sollte jedoch eine Erklärung am Anfang der Die meisten Dokumentation, in der die verwendeten Konventionen erläutert werden.

Diese Funktion könnte also 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 in der Regel einige Standards für alle Dokumentationen in Bezug auf API/Programmierung. Allerdings kann es in jeder Dokumentation feine Unterschiede geben. Als Power-User oder Entwickler wird von Ihnen erwartet, dass Sie in der Lage sind, die Dokumente/Frameworks/Bibliotheken zu lesen und zu verstehen, die Sie zu verwenden versuchen.

Answer 2

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

Für Klammern und dergleichen gibt es normalerweise einen Abschnitt über Codekonventionen, der die genaue Verwendung außerhalb von wörtlichen Beispielen erklären sollte; obwohl EBNF , Regex y Eisenbahn-Diagramme sind fast allgegenwärtig, so dass Sie mit ihnen vertraut sein sollten, um die meisten Notationen zu verstehen.

Answer 3

Die Klammern bedeuten, dass die Eigenschaft optional ist. Beachten Sie jedoch, dass Sie, wenn Sie eine Eigenschaft auf dem n-ten Rang festlegen wollen, entweder Eigenschaften für den führenden Rang 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

Answer 4

Ich hatte vor einiger Zeit dieselbe Frage und jemand wies mich auf Erweiterte Backus-Naur-Form .

Das ist sinnvoll, denn mit Hilfe der Programmierung lassen sich potenziell unbegrenzte Ergebnisse erzielen. Die Dokumentation kann nicht für jeden möglichen Fall ein Beispiel zeigen. Ein gutes Beispiel für den allgemeinen Gebrauch ist hilfreich, aber sobald man die zugrunde liegende Syntax lesen kann, ist man in der Lage, seinen eigenen Code zu erstellen.