我正在阅读Photoshop,Illustrator和InDesign的JavaScript脚本指南.API真的很难读,因为它假设我知道某些简写约定.问题不仅限于此特定脚本指南.我可以列出几十个出现同样问题的人.
当我将API作为一个24小时不在代码中的人阅读时,我想查看一些内容,并以最基本的形式查看代码的简单示例.但通常一开始就不容易理解它.
这是一个例子.我正在查找如何在Photoshop中通过JavaScript更改项目的颜色.所以我搜索PDF并找到"fillColor".我在文档中找到了这个:
fillPath
([fillColor]
[, mode]
[, opacity]
[, preserveTransparency] [, feather]
[, wholePath] [, antiAlias])
当我读到这篇文章时,乍一看毫无意义.为什么有括号,我怎么知道我不应该在实现中使用它们？为什么括号中有逗号？我知道从我找到的样本代码应该是什么样的,这是:
myPath.fillPath(myNewColor)
myPath.fillPath(mynewColor, {
mode: RGB,
opacity: .5
})
如果我没有看到这个例子,我绝对不会从API代码中看出这个方法在实现时的外观.其他人指出这个方法的扩展示例可能如下所示:
fillPath
([fillColor]
[, mode]
[, opacity]
[, preserveTransparency] [, feather]
[, wholePath] [, antiAlias])
好.我看到我可以省略隐含的可选参数.精细.但同样,我绝不会从API中猜到这一点.
那么,某处是否有一些神秘的文件告诉人们如何阅读API文档？为什么这样写？我有什么先验知识？为什么会这样,我该怎么做才能停止对它的疑惑并"得到"它,所以我可以更乐意阅读并实现下一个API？
那么为什么API文档的编写方式会混淆像我这样的常年新手/黑客/ DIY玩家呢？