111

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

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

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

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

myPath.fillPath(myNewColor)

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

4 に答える 4

100

では、なぜAPIドキュメントは、私のような多年生の初心者/ハッカー/ DIYの人を混乱させるような方法で書かれているのでしょうか？

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

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

APIドキュメントの読み方を説明する不思議なドキュメントがどこかにありますか？

実際には、標準またはRFCのsupersekretsyntaxdocがどこにも配置されていませんが、広く使用されているUNIXのmanページシンポシス形式用の30年前のファイルがあります。

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

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

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

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

マイナス記号で始まる引数は、ファイル名が表示される可能性のある位置に表示されている場合でも、ある種のフラグ引数を意味すると解釈されることがよくあります。

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

AdobeAPIから例を分解する

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

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

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

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/プログラミングに関連するすべてのドキュメントにいくつかの標準があります。ただし、各ドキュメントには微妙な違いがある可能性があります。パワーユーザーまたは開発者は、使用しようとしているドキュメント/フレームワーク/ライブラリを読んで理解できることが期待されます。

于 2013-01-16T15:39:44.480 に答える
6

動的に型付けされた言語のAPIドキュメントは、注意深く書かないとあまり意味がない可能性があるため、それほど悪く感じないでください。最も熟練した開発者でさえ、それらを理解しようとするのに苦労する可能性があります。

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

于 2013-01-16T15:08:44.933 に答える
3

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

fillPath() //good
fillPath ( someFillColor ) //good
fillPath ( someFillColor, mode ) //good
fillPath ( undefined, mode ) //good
fillPath ( mode ) //bad
fillPath ( undefined ) //really bad
于 2012-06-08T13:44:00.660 に答える
1

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

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

于 2015-01-04T18:38:31.743 に答える