写API文档 校对完毕

Author: TooBug

chapter2.markdown

@@ -738,26 +738,25 @@ ECMAScript的属性和方法均使用驼峰式命名，尽管包含多个单词
 
 在下一小节我们会讲到，利用注释可以自动生成文档。
 
-================校对分割线================
-## 书写API文档
+## 写API文档
 
-很多人都觉得写文档是一件枯燥且吃力不讨好的事情，但实际情况不是这样。我们可以通过代码注释自动生成文档，这样就不用再去专门写文档了。很多人觉得这是一个不错的点子，因为根据某些关键字和格式化的文档自动生成可阅读的参考手册本身就是“某种编程”。
+很多人都觉得写文档是一件很枯燥而且吃力不讨好的事情，但实际情况并不是这样。我们可以通过代码注释自动生成文档，这样就不用再去专门写文档了。很多人觉得这是一个不错的点子，因为根据某些关键字和特定的格式自动生成可阅读的参考手册本身就是“某种编程”。
 
-传统的APIdoc诞生自Java世界，这个工具名叫“javadoc”，和Java SDK（软件开发工具包）一起提供。但这个创意迅速被其他语言借鉴。JavaScript领域有两个非常优秀的开源工具，它们是JSDoc Toolkit（http://code.google.com/p/jsdoc-toolkit/ ）和YUIDoc（http://yuilibrary.com/projects/yuidoc ）。
+最早利用注释生成API文档的工具诞生自Java业界，这个工具名叫“javadoc”，和Java SDK（软件开发工具包）一起提供，但这个创意迅速被其他语言借鉴。JavaScript领域有两个非常优秀的开源工具，它们是JSDoc Toolkit（<http://code.google.com/p/jsdoc-toolkit/>）和YUIDoc（<http://yuilibrary.com/projects/yuidoc>）。
 
-生成API文档的过程包括：
+生成API文档的过程：
 
-- 以特定的格式来组织书写源代码
+- 以特定的格式来写代码
 - 运行工具来对代码和注释进行解析
 - 发布工具运行的结果，通常是HTML页面
 
-你需要学习这种特殊的语法，包括十几种标签，写法类似于：
+这种语法包括十几种标签（tag），写法类似于：
 
 	/**
 	 * @tag value
 	 */
 
-比如这里有一个函数reverse()，可以对字符串进行反序操作。它的参数和返回值都是字符串。给它补充注释如下：
+比如这里有一个函数`reverse()`，可以对字符串进行反序操作。它的参数和返回值都是字符串。给它补充注释如下：
 
 	/**
 	* Reverse a string
@@ -770,9 +769,9 @@ ECMAScript的属性和方法均使用驼峰式命名，尽管包含多个单词
 		return output;
 	};
 
-可以看到，@param是用来说明输入参数的标签，@return是用来说明返回值的标签，文档生成工具最终会为将这种带注释的源代码解析成格式化好的HTML文档。
+如你所见，`@param`是用来说明输入参数的标签，`@return`是用来说明返回值的标签，文档生成工具最终会将这种带注释的源代码解析成HTML文档。
 
-<a name="a27"></a>
+================校对分割线================
 ### 一个例子：YUIDoc
 
 YUIDoc最初的目的是为YUI库（Yahoo! User Interface）生成文档，但也可以应用于任何项目，为了更充分的使用YUIDoc你需要学习它的注释规范，比如模块和类的写法（当然在JavaScript中是没有类的概念的）。