1.java中注释的两种风格
- 以“/*”开头,以“/*”结束,多行注释
/* * method:main() */
- “//”单行注释
//输出 System.out.println();
- 以“/**”开头,以“*/”结束,这种方式可以用来产生注释文档。
/** * * @param args */
2.为什么要有注释文档。
- 如果文档是与代码分离的,那么每次修改代码都需要修改相应的文档。
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{}
总结:
- 程序似乎只是一系列带有方法的对象的组合,这些方法以其他对象为参数,并发送消息给其他对象。