如何阅读newbs的API文档？ [关闭]-Java 学习之路

我正在阅读Photoshop，Illustrator和InDesign的JavaScript脚本指南 . API真的很难读，因为它假设我知道某些简写约定 . 问题不仅限于此特定脚本指南 . 我可以列出几十个出现同样问题的人 .

当我将API作为一个24小时不在代码中的人阅读时，我想查看一些内容，并以最基本的形式查看代码的简单示例 . 但通常一开始就不容易理解它 .

这是一个例子 . 我正在查找如何在Photoshop中通过JavaScript更改项目的颜色 . 所以我搜索PDF并找到“fillColor” . 我在文档中找到了这个：

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

当我读到这篇文章时，乍一看毫无意义 . 为什么有括号，我怎么知道我不应该在实现中使用它们？为什么括号中有逗号？我知道从我找到的样本代码应该是什么样的，这是：

myPath.fillPath(myNewColor)

如果我没有看到这个例子，我绝对不会从API代码中看出这个方法在实现时的外观 . 其他人指出这个方法的扩展示例可能如下所示：

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

好 . 我看到我可以省略隐含的可选参数 . 精细 . 但同样，我绝不会从API中猜到这一点 .

所以， is there some mysterious document somewhere that tells people how to read API documentation? 为什么这样写？我有什么先验知识？为什么会这样，我该怎么做才能停止对它的疑惑和"get"它，所以我可以更乐意阅读并实现下一个API？

So why is API documentation written in such a way as to confuse perennial newbs / hackers / DIYers like myself?

4 回答

5
So why is API documentation written in such a way as to confuse perennial newbs / hackers / DIYers like myself?

它's really not meant to be written that way. I' ll同意在API文档中似乎没有易用性 . 但是，从旧的 man 样式语法约定到现代API /命名空间约定有很多交叉 .

通常，使用API的人员类型将具有一些开发背景或至少是“超级用户” . 这些类型的用户习惯于这样的语法约定，因此API文档比尝试创建新文档更有意义 .

Is there some mysterious document somewhere that tells people how to read API documentation?

确实没有标准或RFC，supersekretsyntaxdoc在任何地方铺设，但是有一个~30岁的UNIX man page synposis format文件，这是广泛使用的 .

这方面的一些例子（并回答你的问题）将是：

带下划线的单词被视为文字，并且就像它们出现时一样输入 . 参数周围的方括号（[]）表示该参数是可选的 . 省略号......用于表示可以重复前一个参数原型 . 以减号开头的参数 - 通常被认为是某种标志参数，即使它出现在文件名可能出现的位置 .

几乎所有与编程相关的文档都使用这种语法约定，来自Python，man pages，javascript libs（Highcharts）等 .

从Adobe API中分解您的示例
```
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 /编程相关的所有文档中通常都有一些标准 . 但是在每个文档中，都可能存在细微差别 . 作为高级用户或开发人员，您需要能够阅读和理解您尝试使用的文档/框架/库 .
回复于 2024-05-03T20:21:45+08:00
75

如果不仔细编写动态类型语言的API文档可能不是很有意义，所以不要觉得太糟糕，即使是经验最丰富的开发人员也很难理解它们 .

关于括号等，通常有一个代码约定部分，应该解释文字示例之外的确切用法;虽然EBNF，Regex和Railroad Diagrams差不多无处不在，所以你应该熟悉它们以理解大多数符号 .

回复于 2024-05-03T20:21:45+08:00
3
括号表示该属性是可选的 . 请注意，如果要在nTh等级设置soem属性，则必须声明eading属性或将其声明为undefined：
```
fillPath() //good
fillPath ( someFillColor ) //good
fillPath ( someFillColor, mode ) //good
fillPath ( undefined, mode ) //good
fillPath ( mode ) //bad
fillPath ( undefined ) //really bad
```
Loic http://www.loicaigon.com
回复于 2024-05-03T20:21:45+08:00
1

我不久前有同样的问题，有人把我指向Extended Backus–Naur Form .

这是有道理的，因为编程可以用来创造潜在的无限结果 . 文档无法显示每种可能情况的示例 . 常用的一个很好的例子我很有帮助但是一旦你可以阅读基础语法，你就可以创建自己的代码 .

回复于 2024-05-03T20:21:45+08:00

如何阅读newbs的API文档？ [关闭]

4 回答

相关问题