Video在线视频

在一个应用程序中注释非常重要

他不仅用来帮助人们理解代码

而且还能提高程序的可读性

在Java中 注释分为行注释

多行注释和文档注释

行注释 顾名思义就是在代码行的末尾

添加一条注释

方法是使用双斜杠双斜杠之后所有的内容均为注释内容

例如注释x1 y1与玩家的坐标

height width为窗口的高度和宽度

如果你的内容过长无法用一行内容表示

那么就需要使用多行注释

使用/* */ 的语法

保护在/* 和 */之间的所有内容将成为注释

示例中灰色的三行代码都是注释部分

他们在程序执行过程中 都不起任何作用

/* 和 */ 必须成对出现

文档注释的语法和多行注释非常像但略有区别

请同学们仔细看 他的写法是 /** */

而不是/* */

他可以对文件 类方法 甚至是方法中的参数

实例变量进行说明 更神奇的是

Java还提供自动化的文档生成工具

可以将用户描述的这些信息

生产标准的API文件

供程序员们阅读和使用查阅和生产API文档是程序员

必须掌握的基本知识和操作

而这一切的学习 就需要从文档注释开始了解

我们先来看一下jdk提供的String类的文档注释

这里 给出了它的概要结构

除了/** */的基本结构以外 细心的同学可能发现

文档的注释每行都以*开始

这是一个良好的习惯 保持了文档注释的整洁性

同时注释内容中有大量的 Html标签

由于Java提供的文档生成工具 Javadoc

可以将这些注释转换成html页面

这些标签在页面生成中 将起到至关重要的作用

如果你有html经验的话

也可以将相应的标签应用到文档注释中

文档最后通常提供了一些@标签

这些常用的标签描述了一些特定的含义

这里有一张表

提供了常用标签的含义

如这里的author表示文档的作者

这里的version表示该模块的版本

了解了这些内容以后

我们利用今天学过的知识 给猜价格游戏项目添加文档的注释吧

在猜价格游戏项目中

打开task任务列表

在任务列表中 双击选择任务03

跳转到相应位置后

这里要求我们对上一讲中定义的常量 添加行注释语句

方法非常简单 将光标放置在行位

根据描述我们分别写上该行变量的具体含义

比如high price 表示价格上限

Low price 表示价格下限

Limit count 表示猜测次数限制

好了你已经会添加行注释了

照猫画虎 相信你也知道多行注释该怎么写了吧

下面我们来重点看看文档注释的用法

双击任务列表中的任务04

这个任务要求为该类添加类的文档注释

注释内容应该包括文档名项目名 作者等信息

这种文档注释是一种标准化的文档注释

我们会在很多项目文件中 看到都会要写

那么每次都依次敲这些内容是非常的低效无趣的

接下来我们就来学习一种自动化生成文档注释的技巧

打开preference 首选项面板

如果你是Windows系统 它就在window菜单里

在打开的preference首选项对话框左侧列表中

找到代码模板 Code template

对注释commands的 模板进行设置

要求添加类名注释 这里对应的是type

点击编辑edit 修改默认的根据任务要求修改内联模板

我们希望这些信息在html中 以段落形式出现

所以 添加一个 p 标签

克里斯提供了一些 常用的预设变量 描述项目中的相关信息

他们以美元符号 花括号与预设变量形式出现

这里我们预设变量名 就是当前要编辑的文件名

那么可以直接使用 美元符号 花括号 filename 花括号变量

类似的 我们继续添加项目名

修改时间 并在每行后面用br换行 将作者信息用@标注在最后

好了 模板定义好了 单击OK保存

这样的模板定义好了

以后你要在代码中添加类型注释

就会自动的生成这些信息

将光标放置在要生成的类型前 键入/ ** 然后回车

所有的这些信息都自动的生成了

最后我们再来看一个示例学习 方法的文档注释

打开任务05 根据描述添加方法的文档注释

你可能已经猜到就像类型模板一样 eclipse一定为方法也提供了 默认的模板

而这默认的模板的一般的方法文档 注释已经足够用了

下面我们就要来学习调用 该默认模板生成方法注释的方法

只需要在方法名前点击右击

选择source Toggle comments 产生注释

这样 就会非常智能的根据所选的方法参数的返回情况生成 一个方法文档注释

最后我们根据任务要求填上相应的信息方法注释 就写好了

我们添加了类和方法的文档注释

现在是教你变出API文档魔法的时候了

在package Explorer包 浏览视图中

选择项目 单击右键 选择export导出选项

选择Java中的javadoc选项

在打开的向导对话框中

我们只对本项目生成文档

因此去掉其他包的勾选

如果你勾选了private

那么所有的类中的私有的数据也将生成文档

出于对代码的知识产权和信息安全的考虑

如果你要发布给其他的用户使用

通常选择public

这样只有public权限的数据会被导出

单击next 我们接受默认的选择 再单击next

为确保转成的页面中中文没有乱码

如果你的代码是使用特定的编码的你就需要在额外选项文本框中 添加encoding 和charset选项

我在项目中使用的是utf-8的编码格式

因此 这里我们就需要指定编码格式为utf-8

单击finish完成 如果一切正确

只需稍等片刻你的项目中就会多出一个doc文件夹

其中包含若干页面

其中的index.html就是生成的API文档的首页

你可以打开看一下

在Class summary例中的概述

你可以发现我们前面描述的类文档信息

单击method 找到所有类的方法

我们定义的enable input方法 就出现在表格中

单机你可以跳转到该方法的完整信息部分

这里 参数的信息就是我们在任务05中 完成的内容

好 今天我们的任务就完成了你学会了吗