Ich lese die JavaScript-Skriptanleitung für Photoshop, Illustrator und InDesign durch. Die API ist wirklich schwer zu lesen, da davon ausgegangen wird, dass ich bestimmte Kurzformulierungen kenne. Das Problem ist nicht auf diese spezielle Skriptanleitung beschränkt. Ich könnte Dutzende auflisten, die das gleiche Problem darstellen.

Wenn ich eine API als jemand lese, der nicht 24 Stunden am Tag im Code lebt, möchte ich etwas nachschlagen und ein einfaches Beispiel für den Code in Aktion in der einfachsten Form sehen. Aber oft ist es zunächst nicht einfach, einen Sinn daraus zu ziehen.

Hier ist ein Beispiel. Ich suche nach Informationen zum Ändern der Farbe eines Elements mit JavaScript in Photoshop. Also durchsuche ich das PDF und finde "fillColor". Ich finde das in den Dokumenten:

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

Wenn ich das lese, macht es auf den ersten Blick keinen Sinn. Warum gibt es Klammern und woher weiß ich, dass ich sie nicht in einer Implementierung verwenden soll? Warum stehen in den Klammern Kommas? Ich weiß, was der Code istsollte Sieht aus wie aus einer Probe, die ich gefunden habe:

myPath.fillPath(myNewColor)

Wenn ich das Beispiel nicht gesehen hätte, würde ich NIEMALS aus dem API-Code erraten, wie diese Methode bei der Implementierung aussehen sollte. Jemand anderes wies darauf hin, dass ein erweitertes Beispiel für diese Methode folgendermaßen aussehen könnte:

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

OK. Ich sehe, ich kann implizite optionale Parameter weglassen. Fein. Aber auch dies hätte ich NIE von der API erraten.

So,Gibt es irgendwo ein mysteriöses Dokument, das den Leuten sagt, wie man API-Dokumentation liest? Warum ist es so geschrieben? Welche Vorkenntnisse habe ich vorausgesetzt? Warum ist es so und wie kann ich aufhören, mich darüber zu wundern und es "zu bekommen", damit ich die nächste API besser lesen und implementieren kann?

Warum ist die API-Dokumentation so geschrieben, dass sie beständige Newbs / Hacker / Heimwerker wie mich verwirrt?