Java注释和嵌入式文档----学习笔记

java里面有两种注释风格
一种是传统的c语言风格,以 /开始 /结束
第二种也源于c++ , 单行以 // 开始

注释文档
javadoc 用于提取注释的工具,它采用了java编译器的某些技术,查找程序里面特殊注释标签 . 它不仅解析由这些标签标记的信息 , 也将毗邻注释的类名或方法抽取出来

javadoc输出的是一个html文件 , 可以用web浏览器查看 ,

语法
所有的javadoc命令都只能在 /** 注释出现
使用javadoc的方式主要有两种
1: 嵌入html
2:使用文档标签

独立文档标签是一些以 @ 字符开头的命令 , 且置于注释行的最前面
行内文档标签可以出现在javadoc注释中的任何地方,也是以 @ 开头,但要在花括号内

一共有三种类型的注释文档 , 分别对应于注释位置后面的三种元素 : 类 , 方法 , 和域
// : object/Documentation1.java
/* A class comment /
public class Documentation1{
/* A field comment /
public int i ;
/* A method comment /
public void f(){}
}

!!! 注意 : javadoc 只能为public(公共)和 protected(受保护)的成员进行文档注释 , private和包内可访问成员的注释会被忽略掉 , 所以在输出结果中看不到他们 , (不过可以用 -private进行标记 , 以便把private成员的注释也包括在内)

嵌入式HTML
javadoc通过生成的html文档传送html命令 , 这使你能够充分利用html ,当然 , 最主要的还是为了对代码进行格式化 , 例如 :
// ：object/Documentation2.java
/**
*《pre》
*Sysem.out.println(new Date());
*《/pre》
*/

也可以像在其他web文档中那样运用html , 对普通文本按照你自己所描述的进行格式化:

// : object/Documentition3.java
/**
*You can even insert a list
*像写html一样写
*
*/

!!!注意: javadoc会对所有的内容重新格式化 , 使其与标准的文档外观一致 , 不要在嵌入式html中使用标题标签如 h1 或者 hr , 因为javadoc会插入自己的标题
所有的类,方法和域都支持嵌入式html

标签实例
@see : 引用其他类

@see标签允许用户引用其他类的文档, javadoc会在其生成的html文件中 , 通过@see标签链接到其他文档. 格式如下 :
@see classname
@see fully-qualified-classname
@see fully-qualified-classname#method-name
上面的每种格式都会在生成的文档中加入一个具有超链接的 ” See Also”(参见)条目 . 但是javadoc不会检查这些超链接是否有效

{@link package.class#member label}

该标签和@see及其相似, 只是他用于行内 , 并且使用 label作为超链接文本而不用 See Also

{@docRoot}

该标签产生到文档根目录的相对路劲 , 用于文档树页面的显示超链接

{@inheritDoc}

该标签从当前这个类的最直接的基类中继承相关文档到当前的文档注释中

@version 版本信息

@author 作者信息

@since 用来指定所用的jdk版本的情况

@param 用于方法文档中
@param paramter-name description 其中 , paramter-name是方法的参数列表中的标识符 ,description是可延续数行的文本

@return 用于方法文档 描述返回值的含义

@throws 描述异常信息 后面跟异常名字+信息
@throws fully-qualified-class-name description

@deprecated 指出一些旧特性已由改进的新特性取代

示例
//:object/HelloDate.java

import java.util.Date;

/**The first Thinking in java example program.
* Displays a string and today’s date
* @author yaoyuan
* @author www.MindView.net
* @version 4.0
* Created by Administrator on 2017/6/21 0021.
*/
public class HelloDate {
/**
* Entrv doint to class & application.
* @param args array of string arguments
* @throws exceptions No exception thrown
*/
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 MDT 200s
*/
}
///:~