Merge pull request lingcoder#258 from lzf971107/master

Commit And Update

docs/book/21-Arrays.md

@@ -4,7 +4,7 @@
 # 第二十一章 数组
 
 
-> 在[初始化和清理](/book/06-Housekeeping.md)一章的最后，你已经学过如何定义和初始化一个数组。
+> 在[初始化和清理](/docs/book/06-Housekeeping.md)一章的最后，你已经学过如何定义和初始化一个数组。
 
 简单来看，数组需要你去创建和初始化，你可以通过下标对数组元素进行访问，数组的大小不会改变。大多数时候你只需要知道这些，但有时候你必须在数组上进行更复杂的操作，你也可能需要在数组和更加灵活的 **集合** (Collection)之间做出评估。因此本章我们将对数组进行更加深入的分析。
 
@@ -19,7 +19,7 @@
 
 将数组和其他类型的集合区分开来的原因有三：效率，类型，保存基本数据的能力。在Java中，使用数组存储和随机访问对象引用序列是非常高效的。数组是简单的线性序列，这使得对元素的访问变得非常快。然而这种高速也是有代价的，代价就是数组对象的大小是固定的，且在该数组的生存期内不能更改。
 
-速度通常并不是问题，如果有问题，你保存和检索对象的方式也很少是罪魁祸首。你应该总是从 **ArrayList** (来自 [集合]( ))开始，它将数组封装起来。必要时，它会自动分配更多的数组空间，创建新数组，并将旧数组中的引用移动到新数组。这种灵活性需要开销，所以一个**ArrayList**的效率不如数组。在极少的情况下效率会成为问题，所以这种时候你可以直接使用数组。
+速度通常并不是问题，如果有问题，你保存和检索对象的方式也很少是罪魁祸首。你应该总是从 **ArrayList** (来自 [集合](/docs/book/12-Collections.md ))开始，它将数组封装起来。必要时，它会自动分配更多的数组空间，创建新数组，并将旧数组中的引用移动到新数组。这种灵活性需要开销，所以一个**ArrayList**的效率不如数组。在极少的情况下效率会成为问题，所以这种时候你可以直接使用数组。
 
 
 数组和集合(Collections)都不能滥用。不管你使用数组还是集合，如果你越界，你都会得到一个 **RuntimeException** 的异常提醒，这表明你的程序中存在错误。
@@ -91,7 +91,7 @@ Sphere 9
 */
 ```
 
-**Suppliers.create()**  方法在[泛型](/book/20-Generics.md)中被定义。上面两种保存对象的方式都是有类型检查的，唯一比较明显的区别就是数组使用[ ] 来随机存取元素，而一个List 使用诸如add()和get()等方法。数组和ArrayList之间的相似是设计者有意为之，所以在概念上，两者很容易切换。但是就像你在[集合](book/12-Collections.md)中看到的，集合的功能明显多于数组。随着Java自动装箱技术的出现，通过集合使用基本数据类型几乎和通过数组一样简单。数组唯一剩下的优势就是效率。然而，当你解决一个更加普遍的问题时，数组可能限制太多，这种情形下，您可以使用集合类。
+**Suppliers.create()**  方法在[泛型](/docs/book/20-Generics.md)中被定义。上面两种保存对象的方式都是有类型检查的，唯一比较明显的区别就是数组使用[ ] 来随机存取元素，而一个List 使用诸如add()和get()等方法。数组和ArrayList之间的相似是设计者有意为之，所以在概念上，两者很容易切换。但是就像你在[集合](/docs/book/12-Collections.md)中看到的，集合的功能明显多于数组。随着Java自动装箱技术的出现，通过集合使用基本数据类型几乎和通过数组一样简单。数组唯一剩下的优势就是效率。然而，当你解决一个更加普遍的问题时，数组可能限制太多，这种情形下，您可以使用集合类。
 
 
 ### 用于显示数组的实用程序
@@ -361,7 +361,7 @@ public class IceCreamFlavors {
 
 **flaverset()** 创建名为 **results** 的 **String** 类型的数组。 这个数组的大小 **n** 取决于你传进方法的参数。然后选择从数组 **FLAVORS** 中随机选择flavors并且把它们放进 **results** 里并返回。返回一个数组就像返回其他任何的对象一样，实际上返回的是引用。数组是在 **flavorSet()** 中或者在其他的什么地方创建的并不重要。垃圾收集器会清理你用完的数组，你需要的数组则会保留。
 
-如果你必须要返回一系列不同类型的元素，你可以使用 [泛型](book/generics) 中介绍的 **元组** 。
+如果你必须要返回一系列不同类型的元素，你可以使用 [泛型](/docs/book/20-Generics.md) 中介绍的 **元组** 。
 
 注意，当 **flavorSet()** 随机选择 flavors，它应该确保某个特定的选项被选中。这在一个 **do** 循环中执行，它将一直做出随机选择直到它发现一个元素不在 **picked** 数组中。（一个字符串
 

docs/book/Appendix-Javadoc.md

@@ -13,6 +13,42 @@ Javadoc输出为一个html文件，您可以使用web浏览器查看它。对于
 
 以下是对Javadoc基础知识的介绍和概述。在 JDK 文档中可以找到完整的描述。
 
+## 句法规则
+
+所有Javadoc指令都发生在以 **/**** 开头(但仍然以 ***/** 结尾)的注释中。
+
+使用Javadoc有两种主要方法:
+
+嵌入HTML或使用“doc标签”。独立的doc标签是指令它以 **@** 开头，放在注释行的开头。(然而，前面的 ***** 将被忽略。)可能会出现内联doc标签
+
+Javadoc注释中的任何位置，也可以，以一个 **@** 开头，但是被花括号包围。
+
+有三种类型的注释文档，它们对应于注释前面的元素:类、字段或方法。也就是说，类注释出现在类定义之前，字段注释出现在字段定义之前，方法注释出现在方法定义之前。举个简单的例子:
+
+```java
+
+// javadoc/Documentation1.java 
+/** 一个类注释 */
+public class Documentation1 {
+    /** 一个属性注释 */
+    public int i;
+    /** 一个方法注释 */ 
+    public void f() {}
+}
+
+```
+
+Javadoc处理注释文档仅适用于 **公共** 和 **受保护** 的成员。 
+
+默认情况下，将忽略对 **私有成员** 和包访问成员的注释（请参阅["隐藏实现"](/docs/book/07-Implementation-Hiding.md)一章），并且您将看不到任何输出。 
+
+这是有道理的，因为仅客户端程序员的观点是，在文件外部可以使用 **公共成员** 和 **受保护成员** 。 您可以使用 **-private** 标志和包含 **私人** 成员。
+
+要通过Javadoc处理前面的代码，命令是：
+
+**javadoc Documentation1.java**
+
+这将产生一组HTML文件。 如果您在浏览器中打开index.html，您将看到结果与所有其他Java文档具有相同的标准格式，因此用户对这种格式很熟悉，并可以轻松地浏览您的类。
 
 <!-- 分页 -->