第二章.一切都是对象之注释和嵌入式文档javaDoc

1.java中注释的两种风格

1. 以“/*”开头，以“/*”结束,多行注释
   

   /* * method:main() */

   
   
2. “//”单行注释
   

   //输出System.out.println();

   
   
3. 以“/**”开头，以“*/”结束，这种方式可以用来产生注释文档。
   

   /** *  * @param args */

2.为什么要有注释文档。

1. 如果文档是与代码分离的，那么每次修改代码都需要修改相应的文档。
   

3.解决方法

• 将文档与代码“链接”起来，将所有的东西都放在一个文件内。
• 使用一种特殊的注释语法来标记文档。
• 需要一个工具，用于提取那些注释，并将其转换成有用的形式，如doc。

4.javadoc

• javadoc是用于提取注释的工具，他是jdk的一部分。
• javadoc采用编译器的某些技术，查找程序内的特殊注释标签，并且将毗邻注释的雷鸣和方法名抽取出来，用来生成文档。
  
• javadoc的输出是一个html文件，可以使用web浏览器查看。
• 可以通过编写自己的被称为“doclets”的javadoc处理器来生成自己想要的javadoc文档。
  

5.语法

• 所有的javadoc命令都只能在“/**”注释中出现，和通常一样，注释结束于“*/”。
• 使用javadoc的方式主要有两种，
  嵌入HTML（HTML语句）,或者使用“文档标签”。
• 独立文档标签是一些以@开头的命令，且要置于注释行的最前面（但是不算前导“*”之后的最前面）。如：@see
• 行内文档标签可以出现在javadoc注释的任何地方，他们是以“@”开头，但要在花括号内。如：@{link........}
• 共有三种类型的注释文档，分别对应于注释位置后面的三种元素：类、域、和方法。
  

  /** * 类注释文档 * @author Administrator * */public class Test {/** * 域注释文档 */public int i;/** * 方法注释文档 */public void f(){}}

  类注释文档正好位于类定义之前
  域注释文档正好位于域定义之前
  方法注释文档正好位于方法定义之前
  
  

6.需要注意的地方

• javadoc只能为public（公共）和protected（受保护）成员进行文档注释。private(私有的)和包内可访问成员会被忽略掉，所以输出的HTML文档看不到他们，
• 可以使用-private进行标记，以便把private成员的注释也包括在内。

7.嵌入式HTML

• javadoc能够通过生成HTML文档传送HTML命令，这使你能够充分利用HTML。其主要目的还是对代码进行格式化。
  

  /** * <pre> * System.out.println(new Date()); * </pre> * */

• 也可以像web文档中那样运用HTML。
  

  /** *<ol> *<li>Item one *<li>Item two *<li>Item three *  </ol> * */

  
  
• 注意：在注释文档中，位于每一行开头的型号和前导空格都会被javadoc丢弃。
• javadoc会对所有内容重新格式化，使其与标准的文档外观一致。
• 不要在HTML中使用标题标签，如<h1><hr>，因为javadoc会插入自己的标题，而自己定义的标题可能会与之发生冲突。
  
  

8.编码风格

• 类名首字母大写。驼峰风格。如class ClassAllTheColorsOfTheRaihrow{}

总结：

• 程序似乎只是一系列带有方法的对象的组合，这些方法以其他对象为参数，并发送消息给其他对象。