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

问题描述

我读通过JavaScript脚本指南包括Photoshop，Illustrator和InDesign。该API是真的很难阅读，因为它假定我知道一定速记约定。该问题并不限于此特定的脚本指南。我可以列出几十个present同样的问题。

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.

当我读到一个API有人不活在code，每天24小时，我想看看东西，看到在最基本的形式在行动code的一个简单的例子。但往往是不容易理解它在第一。

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.

下面是一个例子。我仰望如何由JavaScript在Photoshop中改变一个项目的颜色。所以我搜索PDF，找到填充颜色。我觉得这在docs：

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])

当我读到这，它的第一眼是没有意义的。为什么有括号，我怎么会知道我不应该在执行使用它们？为什么在括号逗号？我知道code的应的样子从样品中，我发现，这是这样的：

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)

如果我没有看到这个例子中，我会从API code，它是实现此方法时，应该如何看NEVER神圣。有人指出，这种方法的扩展的例子可能是这样的：

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
})

确定。我知道我可以离开了隐含的可选参数。精细。但同样，我决不会从API猜到了。

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

因此​​，有一些神秘的文件的地方，告诉人们如何阅读API文档？为什么这样写呢？什么先验知识它假定我有吗？为什么是这样的，我能做些什么来阻止想知道它和搞定它，这样我就可以更快乐阅读并执行下一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?

那么，为什么会写这样的方式来迷惑常年newbs /黑客/ DIY爱好者喜欢自己？API文档

推荐答案

那么，为什么会写这样的方式来迷惑常年newbs /黑客/ DIY爱好者喜欢自己？API文档

这真的不是意味着要写入的方式。我会同意似乎没有缓解整个API单证的使用。但是，在从旧男人有很多交叉的风格语法约定，到现代的API /命名约定。

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.

典型地，人谁与API的工作的类型，将具有在发展或至少一个超级用户的一些背景。这些类型的用户都习惯了这样的语法约定，它更有意义的API文档跟随而不是试图创造新的。

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.

有一些神秘的文件的地方，告诉人们如何阅读API文档？

有真的是没有标准的，或RFC，supersekretsyntaxdoc周围铺设的任何地方，但是有一个约30岁文件UNIX的man页面synposis格式这是wides $ p $垫使用。

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.

省略号...是用来表明previous论点原型可以重复

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.

几乎所有编程相关的文档使用这种类型的语法习惯，从的Python ，的man页中的JavaScript库（ Highcharts ），等。

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

从Adobe API打破你的榜样

Breaking down your example from Adobe API

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

我们看到 fillPath（）（函数）接受可选参数填充颜色，模式，不透明度，preserveTransparency，feathe，wholePath 或抗混叠。调用 fillPath（），你可以从任何地方无合格，所有的，这些参数传递给它的。可选的中的逗号[] 意思是，如果该参数除了别人使用时，您需要的逗号单独它。 （常识有时，肯定的，但有时像VB的一些语言，明确需要这些逗号正确界定哪些参数丢失！）。既然你没有链接到文件（我找不到它在 Adob​​e的脚本页面）有真不是办法知道的Adobe API期待的格式。但是，应该有顶部的最的说明文档中使用的约定。

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

此外，通常有跨越与API /编程的所有单证一些标准。然而，在每个文档，可能有细微的差别。作为超级用户或开发者，你预计将能够阅读和理解你正在尝试使用的文件/框架/库。

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.

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