如何阅读新手的API文档？ [英] How to read API documentation for newbs?

问题描述

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

当我将API看作一个24小时不生活的代码，我想看看并且以最基本的形式看到一个简单的代码行为示例。但是，通常首先不要理解它。

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

  fillPath 
（[fillColor] 
 [，mode] 
 [，opacity] 
 [，preserveTransparency] [，羽毛] 
 [，整个路径] [，antiAlias]）
  

当我阅读这个，乍看之下没有任何意义。为什么有方括号，我怎么知道我不应该在实现中使用它们？为什么括号中有逗号？我知道我发现的一个示例中的代码应该是什么样的，这是这样的：

  myPath .fillPath（myNewColor）
  

如果我没有看到这个例子，我永远不会从API代码就是这个方法在实现时应该如何看待。有人指出，这个方法的扩展示例可能如下所示：

  myPath.fillPath（mynewColor，{
模式：RGB，
不透明度：.5 
}）
  

确定。我看到我可以省略隐含的可选参数。精细。但是再次，我从来没有从API中猜到这个。

所以，有一些神秘的文档告诉人们如何读取API文档？强>为什么这样写？假设我有什么先前的知识？为什么是这样的，我可以做些什么来停止想知道它并得到它，所以我可以更高兴地阅读和实现下一个API？

那么为什么API文档的写作方式可能会混淆像我一样的常年新星/黑客/ DIY？

解决方案

那么为什么API文档用这样的方式混淆像我一样的常年新娘/黑客/ DIY？ p>

真的不是这样写的。我会同意API文档似乎没有任何易用性。然而，从旧的 man 风格语法约定到现代API /命名空间约定有很多交叉。

<通常情况下，使用API​​的人的类型将具有一定的开发背景或至少一个高级用户。这些类型的用户被用于这样的语法约定，并且API API文档比尝试创建新文档更有意义。

是否有一些这个秘密文件告诉人们如何读取API文档？

真的没有标准，或者RFC，supersekretsyntaxdoc放置在任何地方，但是有一个〜 30岁的UNIX文件手册页synposis格式被广泛使用。

这个例子（并回答你的问题）将是：

$ b $下划线的单词被视为文字，并且按照它们的形式进行打字。

参数周围的方括号（[]）表示参数是可选的。 / p>

椭圆...用于表明以前的参数原型可能会重复。

参数开头使用减号 - 通常被认为是指某种标志参数，即使它出现在文件名可能出现的位置。

几乎所有编程相关的文档都使用这种类型的语法约定，从 Python ， 手册页，javascript libs（ Highcharts ）等。

---

打破你的来自Adobe API的示例

  fillPath 
（[fillColor] 
 [，mode] 
 [ ，opacity] 
 [，preserveTransparency] [，羽毛] 
 [，整个路线] [，antiAlias]）
  

我们看到 fillPath（）（一个函数）接受可选参数 fillColor，mode，opacity，preserveTransparency，feathe，wholePath 或 antiAlias 。调用 fillPath（），你可以传递任何地方从这些参数中的任何一个到所有参数。可选的 [] 中的逗号表示如果除了其他用户使用此参数，则需要使用逗号分隔。 （常识有时候肯定的，但有时候一些VB语言，显然需要这些逗号来恰当地描述哪个参数丢失！）。由于您没有链接到文档（并且我无法在 Adob​​e的脚本页面）真的没有办法知道Adobe API所期望的格式。但是，在大多数文档的顶部应该有一个解释，解释其中使用的约定。

所以，这个函数可能会被使用很多方法：

  fillPath（）//没有通过
 fillPath（＃000000，RGB）//黑色，RGB模式
 fillPath（＃000000，RGB，50）//黑色，RGB模式，半透明度
 
 //现在它变得棘手，这可能也是可以接受的：
 fillPath （＃000000,50）//黑色，无模式，半透明度
 
 // OR 
 fillPath（＃000000，，50）//黑色，无模式，半透明度
  

同样，与API /编程相关的所有文档通常都有一些标准。然而在每个文档中，可能会有微妙的差异。作为强大的用户或开发人员，您希望能够阅读并理解您尝试使用的文档/框架/库。

I'm reading through the JavaScript scripting guide for Photoshop, Illustrator and InDesign. The API is really hard to read because it assumes I know certain shorthand conventions. The problem is not limited to this particular scripting guide. I could list out dozens that present the same problem.

When I read an API as someone that does not live in code 24 hours a day, I want to look something up and see a simple example of the code in action in the most basic form. But often it's not easy to make sense of it at first.

Here is an example. I'm look up how to change the color of an item by JavaScript in Photoshop. So I search the PDF and find "fillColor". I find this in the docs:

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

When I read this, it at first glance makes no sense. Why are there brackets and how would I know I'm not supposed to use them in an implementation? Why are commas in the brackets? I know what the code should look like from a sample I found, which is this:

myPath.fillPath(myNewColor)

If I hadn't seen the example, I would NEVER divine from the API code that that is how this method should look when implemented. Someone else pointed out that an extended example for this method might look like this:

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

OK. I see I can leave out implied optional parameters. Fine. But again, I NEVER would have guessed this from the API.

So, is there some mysterious document somewhere that tells people how to read API documentation? Why is it written like that? What prior knowledge does it assume I have? Why is it like this, and what can I do to stop wondering about it and "get" it, so I can more happily read and implement the next API?

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

解决方案

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

It's really not meant to be written that way. I'll agree there seems to be no ease of use across API documentations. However, there is a lot of cross over from older man style syntax conventions, to the modern API/namespace conventions.

Typically, the type of person who works with API, will have some background in development or at the least a 'power user'. These types of users are used to such syntax conventions and it makes more sense for the API document to follow than to try to create new ones.

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

There really is no standard, or RFC, supersekretsyntaxdoc laying around anywhere, however there is a ~30 year old file for UNIX man page synposis format which is widespread use.

Some examples of this (and answering your question) would be :

Underlined words are considered literals, and are typed just as they appear.

Square brackets ( [] ) around an argument indicate that the argument is optional.

Ellipses ... are used to show that the previous argument-prototype may be repeated.

An argument beginning with a minus sign - is often taken to mean some sort of flag argument even if it appears in a position where a file name could appear.

Almost all programming related documentation uses this type of syntax convention, from Python, man pages, javascript libs (Highcharts), etc.

---

Breaking down your example from Adobe API

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

We see that fillPath() (a function) takes optional arguments fillColor, mode, opacity, preserveTransparency, feathe, wholePath or antiAlias. Calling fillPath(), you could pass anywhere from none, to all, of those parameters to it. The commas within the optional [] mean that if this parameter is used in addition to others, you need the comma to seperate it. (Common sense sometimes, for sure, but sometimes some languages like VB, explicitly need those commas to properly delineate which parameter is missing!). Since you did not link to the documentation (and I can't find it on Adobe's scripting page) there really is not a way to know which format the Adobe API is expecting. However, there should be an explanation at the top of most documentation explaining the conventions used within.

So, this function could probably be used many ways :

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

Again, there usually are some standards across all documentations relating to API/programming. However in each doc, there could be subtle differences. As a power user, or developer, you ARE expected to be able to read and understand the documents/frameworks/libraries you're attempting to use.

这篇关于如何阅读新手的API文档？的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！