论如何阅读API文档

你是否常常对文档里出现的[]以及各种...有困惑？是否有一些神秘的文件告诉人们如何阅读所有API文档？

6A9787A8-EA86-46A7-9BD6-BE1EC4F50B4F

答案是可能没有什么标准，或者RFC，或者什么神秘文件来告诉我们阅读方法，有些API文档提供者会介绍他们各自文档的阅读方法（一般是extended BNF），而有些则不会，所以这就需要我们知道一些约定俗成的共识，我在这里简单说两个，更多的看得多了也就懂了。

关于[]

参数周围的方括号（[]）表示该参数是可选的。也就意味着可以省略，省略参数的前提是函数能识别你到底想传入的是哪一个参数，所以不管哪个语言，都有类似的约定：

可省略的参数后置
省略参数后不能与其它函数产生二义性 (js不存在这个问题）

程序要求你按参数定义的顺序传递参数进去。如果后面有没传的，就省略了。如果要省略中间的……对不起，自己传入 null 或 undefined。

对于 javascript 来说，可以对参数类型进行简单的判断来进行识别，以达到省略中间参数的效果，比如

var set = function(name, date, age) {
	if (typeof date === "number") {
    	age = date;
	    date = undefined;
	}
	// ....
}

这里是简单通过类型来识别的。更复杂一些的情况可以使用正则表达式来识别 domain， url, email 等，不过说起来就比较麻烦了，而且代码逻辑复杂，也不易写。参数较多，部分可以省略的情况，建议使用参数对象，其他语言也有命名参数之类的特性。es6中已经有一些新式的传递参数的方法，这里不展开介绍了。

关于…

[arg1, arg2...]表示若干可选参数，”…”表示了若干，就是可以有很多，不止一个的意思。

巴科斯范式

如果说有什么源头的话，可能都来自于一个叫巴科斯范式的东西，很多的linux手册以及各种软件的官方文档，所有稍微复杂点儿的语法规则几乎都是它定义的！巴科斯范式(BNF: Backus-Naur Form 的缩写)是由 John Backus 和Peter Naur首先引入的用来描述计算机语言语法的符号集。现在，几乎每一位新编程语言书籍的作者都使用巴科斯范式来定义编程语言的语法规则。

巴科斯范式的内容：

在双引号中的字(“word”)代表着这些字符本身。而double_quote用来代表双引号。
在双引号外的字（有可能有下划线）代表着语法部分。
尖括号( < > )内包含的为必选项。
方括号( [ ] )内包含的为可选项。
大括号( { } )内包含的为可重复0至无数次的项。
竖线( | )表示在其左右两边任选一项，相当于”OR”的意思。
::= 是“被定义为”的意思。

现在在网络上大多数能搜出来的都是extended BNF ，允许使用循环，但正真的BNF只需要递归就够了。