如何阅读newbs的API文档？
我正在阅读Photoshop，Illustrator和InDesign的JavaScript脚本指南。 该API真的很难阅读，因为它假定我知道某些速记约定。 问题不仅限于这个特定的脚本指南。 我可以列出几十个出现同样问题的人。
当我将API读取为一天24小时不在代码中的人时，我想查找一些代码，并以最基本的forms查看代码的一个简单示例。 但是一开始就很难理解它。
这是一个例子。 我正在查看如何在Photoshop中通过JavaScript更改项目的颜色。 所以我searchPDF并find“fillColor”。 我在文档中find这个：
fillPath ([fillColor] [, mode] [, opacity] [, preserveTransparency] [, feather] [, wholePath] [, antiAlias]) 当我读到这个，乍一看是没有意义的。 为什么有括号，我怎么知道我不应该在执行中使用它们？ 为什么在括号中的逗号？ 我知道从我find的示例代码应该是什么样子，这是这样的：
myPath.fillPath(myNewColor)
如果我没有看到这个例子，那么我绝对不会从API代码中获益，那就是这个方法在实现时应该看起来如何。 其他人指出，这个方法的扩展例子可能是这样的：
myPath.fillPath(mynewColor, { mode: RGB, opacity: .5 })
好。 我看到我可以省略隐含的可选参数。 精细。 但是，我再也不会从API中猜出来。
那么， 是否有一些神秘的文件告诉人们如何阅读API文档？ 为什么这样写呢？ 假设我有什么先验知识？ 为什么这样，我该怎么做才能停止对它的思考和“获取”，所以我可以更高兴地阅读和实现下一个API？
那么为什么API文档是以这样的方式编写的，以至于像我一样混淆了常年的新手/黑客/ DIY的？
那么为什么API文档是以这样的方式编写的，以至于像我一样混淆了常年的新手/黑客/ DIY的？
这并不意味着要这样写。 我会同意，在API文档中似乎没有任何易用性。 然而，从旧式风格的语法约定到现代的API /命名空间惯例都有很多的交叉。
通常，使用API的人员types将具有一定的开发背景，或者至less是“超级用户”。 这些types的用户习惯于这样的语法约定，API文档更有意义，而不是尝试创build新的。
是否有一些神秘的文件告诉人们如何阅读API文档？
实际上没有任何标准，或RFC，supersekretsyntaxdoc随处可见，但是对于UNIX 手册页synposis格式有一个30年前的文件，这是广泛使用的。
这个（并回答你的问题）的一些例子是：
加下划线的单词被认为是文字，并按照其出现的方式键入。
参数周围的方括号（[]）表示该参数是可选的。
椭圆…用来表示前面的参数原型可能会重复。
一个以减号开始的参数 – 通常被认为是某种标志参数，即使它出现在文件名可能出现的位置。
几乎所有与编程相关的文档都使用这种types的语法约定，从Python ， 手册页 ，JavaScript库（ Highcharts ）等
从Adobe API中分解您的示例
fillPath ([fillColor] [, mode] [, opacity] [, preserveTransparency] [, feather] [, wholePath] [, antiAlias])
我们看到fillPath() （一个函数）接受了可选参数fillColor, mode, opacity, preserveTransparency, feathe, wholePath或antiAlias 。 调用fillPath() ，你可以传递给它的任何地方， fillPath()到所有的参数。 可选[]的逗号表示如果除了别人之外还使用了这个参数，则需要使用逗号来分隔它。 （有时常识，当然，但有时候像VB这样的语言，明确地需要这些逗号来正确描述哪些参数丢失！）。 由于您没有链接到文档（并且我无法在Adobe的脚本页面上find它），所以实际上没有办法知道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 /编程有关的文档通常都有一些标准。 但是在每个文档中，可能会有细微的差异。 作为高级用户或开发人员，您期望能够阅读和理解您正在尝试使用的文档/框架/库。
对于dynamictypes语言的API文档，如果不是很仔细地写，就不是很有意义，所以也不要太在意，即使是最经验丰富的开发人员也难以理解它们。
关于方括号等，通常有一个代码规范部分，应该解释字面示例以外的确切用法; 虽然EBNF ，正则expression式和铁路图几乎无处不在，所以你应该熟悉它们来理解大多数符号。
括号表示该属性是可选的。 请注意，如果你想在第n级设置soem属性，你必须为eading声明属性或者声明它们为undefined：
fillPath() //good fillPath ( someFillColor ) //good fillPath ( someFillColor, mode ) //good fillPath ( undefined, mode ) //good fillPath ( mode ) //bad fillPath ( undefined ) //really bad
我有一个相同的问题，有人指出我扩展巴克斯 – 诺尔forms 。
这是有道理的，因为编程可以用来创造潜在的无限的结果。 文档无法显示每个可能情况的示例。 一个很好的常用示例我很有帮助，但是一旦您可以读取底层语法，您就可以创build自己的代码。
