web-dev-qa-db-ja.com

APIドキュメンテーション関数パラメーターの解釈方法

APIドキュメントの関数インターフェイスの構文を解釈する標準はありますか？

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

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

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

myPath.fillPath(myNewColor)

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

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

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

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

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

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

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

下線付きの単語はリテラルと見なされ、表示されるとおりに入力されます。

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

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

マイナス記号で始まる引数-ファイル名が表示される可能性のある位置に表示される場合でも、多くの場合、何らかのフラグ引数を意味します。

ほとんどすべてのプログラミング関連ドキュメントでは、 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が期待しているフォーマットを知る方法はありません。ただし、mostドキュメントの上部で、内部で使用される規則を説明する説明が必要です。

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

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

80
PenguinCoder

動的に型付けされた言語のAPIドキュメントは、注意深く書かれていなければあまり意味がないので、それについてあまり気にしないでください。

括弧などについては、通常、リテラルの例以外の正確な使用法を説明するコード規則セクションがあります。 [〜＃〜] ebnf [〜＃〜] 、 正規表現 、および 鉄道図 はほぼどこにでもあるので、それらに精通している必要がありますほとんどの表記法を理解します。

5
fortran

括弧は、プロパティがオプションであることを意味します。ただし、nThランクでsoemプロパティを設定する場合は、イーディングプロパティのプロパティを宣言するか、未定義として宣言する必要があります。

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

ロイック http://www.loicaigon.com

3
Loic Aigon

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

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

1
StevenKW