newbsのAPIドキュメントを読むには？

Question

私は、Photoshop、Illustrator、およびInDesignのJavaScriptスクリプトガイドを読んでいます。 APIは、私が特定の短縮形の規則を知っていることを前提としているため、読みにくいです。問題は、この特定のスクリプトガイドに限定されません。私は同じ問題を提示する数十を列挙することができました。

コードを24時間生きていない人としてAPIを読むと、何かを見て、最も基本的な形式のコードの簡単な例を見たいと思います。しかし、最初はそれを理解するのは容易ではないことがよくあります。

ここは例です。私は、PhotoshopでJavaScriptを使って項目の色を変更する方法を見ています。だから私はPDFを検索し、 "fillColor"を見つける。私は文書でこれを見つける：

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

私がこれを読むと、それは一見しても意味がありません。なぜ括弧があるのですが、実装でそれらを使用するはずがないことをどのように知っていますか？かっこ内にカンマがあるのはなぜですか？それはどのようにこの方法であることをAPIコードから私は神のだろう、私は例を見ていない場合は

myPath.fillPath(myNewColor) 

：私は、コードがこれで私が見つけたサンプルからどのように見えるかを知っています実装時に見えるはずです。他の人は、このメソッドの拡張例が次のようになることを指摘しました。

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

OK。私は暗黙のオプションのパラメータを除外することができます。ファイン。しかし、再び、私はAPIからこれを推測したことはありません。

だから、には、APIドキュメントを読む方法を伝える謎の文書がありますか？なぜそれはそのように書かれていますか？私にはどのような事前知識があると仮定していますか？なぜそれがこのようなものなのでしょうか？それについて疑問を感じることを止め、それを「取得」するために何ができるのですか？次のAPIをもっと楽しく読んで実装できますか？

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

Answer 1

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

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

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

APIドキュメントを読む方法を伝える謎の文書がありますか？

実際にはどこにも置かれていない標準やRFC、supersekretsyntaxdocはありませんが、普及しているUNIXのman page synposis formatの場合、〜30歳のファイルがあります。

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

下線の単語を考慮リテラルであり、彼らが現れると同じように型付けされています。

引数の前後の角かっこ（[]）は、引数がオプションであることを示します。

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

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

は、ほとんどすべてのプログラミング関連ドキュメントは、Adobe社のAPIからあなたの例を分解など

---

Python、man pages、JavaScriptのLIBS（Highcharts）、から、構文規則のこのタイプを使用しています

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

fillPath()（関数）は、オプションの引数fillColor, mode, opacity, preserveTransparency, feathe, wholePathまたはantiAliasを使用しています。 fillPath()を呼び出すと、それらのパラメータのうち、どこからもすべてを渡すことができます。オプションの[]のコンマは、このパラメータを他のパラメータに加えて使用する場合は、カンマで区切る必要があることを意味します。 （時には、時には常識的ですが、VBのようないくつかの言語では、どのパラメータが欠落しているかを正確に記述するためにこれらのカンマが明示的に必要です）。あなたはドキュメントにリンクしていないので（私はAdobe's scripting pageにありません）、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 /プログラミングに関連するすべてのドキュメンテーション全体でいくつかの基準があります。しかし、それぞれの文書には微妙な違いがあるかもしれません。パワーユーザーまたは開発者は、使用しようとしているドキュメント/フレームワーク/ライブラリを読んで理解することができます。

Answer 2

大括弧は、プロパティがオプションであることを意味します。動的ため

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

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

Answer 3

APIドキュメント：それあなたがn番目のランクでsoemプロパティを設定したい場合は、あなたがeading 1のプロパティを宣言するか、未定義として宣言するか持っているかの点に注意してください型付きの言語は、慎重に書かれていなければ意味がありませんので、あまり気にしないでください。最も熟練した開発者であっても、理解するのは苦労します。

大括弧などについては、通常、リテラルの例以外の正確な使用法を説明するコード表記セクションがあります。 EBNF、Regex、Railroad Diagramsはほとんどどこにでもありますので、ほとんどの表記を理解するにはそれらに精通している必要があります。

Answer 4

私はこの同じ質問をしばらく前に返して、誰かが私にExtended Backus–Naur Formと指摘しました。

プログラミングは潜在的な無限の結果を作成するために使用できるので意味があります。ドキュメントには、すべての可能性のあるケースの例は表示されません。一般的な使い方の良い例私は役に立ちましたが、基本的な構文を読むことができれば、独自のコードを作成することができます。