APIドキュメント関数のパラメーターを解釈する方法は？

APIドキュメントの関数インターフェイスの構文を解釈するための標準はありますか？ある場合、それはどのように定義されますか？

アイテムの色を変更する方法の例は、「fillColor」関数用のPhotoshopのJavaScriptスクリプトガイドです。

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

括弧の意味は何ですか？括弧内にコンマがあるのはなぜですか？これは次の呼び出し例とどのように関連していますか？

myPath.fillPath(myNewColor)

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

では、なぜAPIのドキュメントは、私のような恒久的なnewb /ハッカー/ DIYを混乱させるような方法で書かれているのですか？

それはそのように書かれることを本当に意図されていません。APIドキュメント全体で使いやすさはないようだと私は同意します。ただし、古いmanスタイルの構文規則から、最新のAPI /名前空間の規則まで、多くのクロスオーバーがあります。

通常、APIを使用するタイプの人は、開発にある程度のバックグラウンドがあるか、少なくとも「パワーユーザー」です。これらのタイプのユーザーは、そのような構文規則に慣れているため、新しいAPIを作成するよりも、APIドキュメントに従う方が理にかなっています。

APIドキュメントの読み方を教えている不思議なドキュメントはどこかにありますか？

本当にどこにも標準またはRFCのsupersekretsyntaxdocはありませんが、広く使用されているUNIXのmanページのSynposis形式用の〜30年前のファイルがあります。

これのいくつかの例（そしてあなたの質問に答える）は：

下線が引かれた単語はリテラルと見なされ、表示されるとおりに入力されます。

引数を囲む角括弧（[]）は、引数がオプションであることを示します。

省略記号...は、前の引数プロトタイプが繰り返される可能性があることを示すために使用されます。

マイナス記号で始まる引数-ファイル名が出現する可能性のある位置にある場合でも、ある種のフラグ引数を意味するとしばしば解釈されます。

ほとんどすべてのプログラミング関連のドキュメントは、Python、manページ、javascript libs（Highcharts）などから、このタイプの構文規則を使用しています。

Adobe APIからの例の分析

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

fillPath()（関数）がオプションの引数fillColor, mode, opacity, preserveTransparency, feathe, wholePathまたはを受け取ることがわかりますantiAlias。を呼び出すとfillPath()、これらのパラメーターのどれもなしからすべてに渡すことができます。オプション内のコンマは、[]このパラメーターを他のパラメーターに加えて使用する場合、コンマで区切る必要があることを意味します。（常識的には確かに、時にはVBのような一部の言語では、欠落しているパラメーターを適切に記述するために、これらのコンマを明示的に必要とします！）。ドキュメントにリンクしていなかったため（およびAdobeのスクリプトページにそれが見つからないため）、Adobe APIがどの形式を想定しているのかを知る方法は実際にはありません。ただし、ほとんどのドキュメントの上部に、その中で使用されている規則を説明する説明があります。

したがって、この関数はおそらく多くの方法で使用できます。

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

繰り返しますが、通常、API /プログラミングに関連するすべてのドキュメントにいくつかの標準があります。ただし、各ドキュメントには微妙な違いがある場合があります。パワーユーザーまたは開発者は、使用しようとしているドキュメント/フレームワーク/ライブラリを読んで理解できることが求められます。

動的に型付けされた言語のAPIドキュメントは、注意深く書かれていないとあまり意味がありません。そのため、あまり気にしないでください。熟練した開発者であっても、理解するのに苦労する場合があります。

大括弧などについては、通常、リテラルの例の外での正確な使用法を説明するコード規則のセクションがあります。がEBNF、正規表現と鉄道図は、ほぼ遍在しているので、あなたは、ほとんどの表記を理解するためにそれらに精通している必要があります。

大括弧は、プロパティーがオプションであることを意味します。ただし、nThランクでプロパティを設定する場合は、先頭のプロパティを宣言するか、未定義として宣言する必要があることに注意してください。

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

しばらく前に同じ質問があり、誰かがExtended Backus–Naur Formを指摘しました。

プログラミングを使用して潜在的に無限の結果を作成できるため、これは理にかなっています。ドキュメントは、すべての可能なケースの例を表示できるわけではありません。一般的な使用の良い例は参考になりますが、基礎となる構文を読み取ることができれば、独自のコードを作成できます。