Java编程思想第四版——第六天

2012-03-27
66-70/913

最近两天有点忙，都没顾上看书了。

2.8.2 语法
所有javadoc命令都只能在“/**”注释中出现，注释结束于“*/”。
使用javadoc两种方式：嵌入HTML，或使用“文档标签”。独立文档标签：以@开头的命令，置于注释行的最前面（前导“* ”之后）。“行内文档标签 ”可以出现在javadoc注释中的任何地方，也以@开头，括在花括号内。

三种类型的注释文档，分别对应于注释位置后面的三种元素：类、域和方法。类注释位于类定义之前，域注释位于域定义之前，方法注释位于方法定义之前：
//: object/Documentation1.java
/** A class comment */
public class Documentaticon1{
/** A field comment */
public int i;
/** A method comment */
public void f(){}
} ///:~
Javadoc只能为public和protected成员进行文档注释，private和包内可访问成员的注释会被忽略掉，输出结果中看不到它们（可以用-private进行标记，把private成员的注释也包括在内）。

2.8.3 嵌入式HTML
javadoc通过生成的HTML文档传送HTML命令，能充分利用HTML，主要目的还是为了对代码进行格式化。可以像在web文档中那样运用HTML，对普通文本按照自己所描述的进行格式化。

在文档注释中，位于每一行开头的星号和前导空格都会被javadoc丢弃。
不要在嵌入式HTML中使用标题标签，如<h1>或<hr>，因为javadoc会插入自己的标题，自定义标题可能同它们发生冲突。
所有类型的注释文档——类、域和方法——都支持嵌入式HTML。

2.8.4 一些标签示例
介绍一些可以用于代码文档的javadoc标签。
JDK查阅javadoc参考，学习javadoc的各种不同的使用方法。
1 @see：引用其他类
@see标签允许用户引用其他类的文档。通过@see链接到其他文档。
格式：
@see classname
@see fully-qualified-classname
@see fully-qualified-classname#method-name
每种格式会在文档中加入一个具有超链接的“See Also”（参见）条目，javadoc不会检查所提供的超链接是否有效。

2 {@link package.class#member label}
与@see极其相似，只是它用于行内，用“label”作为超链接文本而不用“See Also”。

3 {@docRoot}
产生到文档根目录的相对路径，用于文档树页面的显示超链接。

4 {@inheritDoc}
从当前这个类的最直接的基类中继承相关文档到当前的文档注释中。

5 @version
格式：@version version-information
版本信息
version-information可以是任何适合包含在版本说明中的重要信息。
Javadoc命令使用“-version”，标记，从生成的HTML文档中特别提取出版本信息。

6 @author
格式：@author author-information
可以使用多个标签，列出所有作者，必须连续放置。

7 @since
指定程序代码最早使用的版本，java文档中它被用来指定所用的JDK版本情况。

8 @param
用于方法文档

9 @return
用于方法文档

10 @throws
异常

11 @deprecated
指出一些旧特性已由改进的新特性所取代，建议用户不要再使用这些旧特性，因为将来它们可能会被删除。使用标记为@deprecated的方法，编译器会发布警告。
Java SE5中，javadoc标签@deprecated已经被@Deprecated注解所替代。

2.8.5 文档示例
//: object/HelloDate.java
import java.util.*;

/** The first Thinking in java example program.
*Displays a String and today`s date.
*/
public class HelloDate{
/** Entry point to class & application.
*@param args array of string arguments
*/
public static void main(String [] args) {
System.out.println(“Hello, it`s:”);
System.out.println(new Date());
}
}/* Output: (55% match)
Hello,it`s:
Wed Oct 05 14:39:36 MDT 2005
*///:~
第一行采用作者自己独特的方法，用一个“：”作为特殊记号说明这是包含源文件名的注释行。最后一行也是一行注释，这个“///:~”标志源代码清单的结束。
/* Output标签表示输出的开始部分将由这个文件生成，通过这种形式，它会被自动地测试以验证其准确性。本例中，（55% match）在向测试系统说明程序的每一次运行和下一次运行输出存在着很大的差异，因此它们与这里列出的输出预期只有55%的相关性。

2.9 编码风格
在“java编程语言编码约定”中，代码风格规定：类名的首字母要大写，如果类名由几个单词构成，那么把它们并在一起（最好不用下划线来分隔名字），其中每个内部单词的首字母都采用大写形式。
这种风格称作“驼峰风格”，几乎其他所有内容——方法、字段（成员变量）以及对象引用名称等，公认的风格与类的风格一样，只是标识符的第一个字母采用小写。
例：
class AllTheColorsOfTheRainbow{
int anIntegerRepresentingColors;
void changeTheHueOfTheColor(int newHue){
//...
}
//...
}
必须键入所有长名字，不能输错，要格外仔细。
SUN程序库中的java代码也采用本书摆放开、闭花括号的方式。

2.10 总结
接触相当多的关于编写一个简单程序的java编程知识，对java语言以及它的一些基本思想做一个总体认识。

2.11 练习
除了javadoc的有关练习，其他都做了一遍。