JavaDoc注释与帮助说明文档

注释

编写程序时，总要为程序添加一些注释，用以说明某段代码的作用，或者某个类的用途、某个方法的功能，以及该方法的参数及返回值的意义。

为什么要编写注释？

1. 不要太过自信自己的理解能力。当你思路流畅，进入变成境界时，你可能很快地实现某个功能。但在以后再次阅读这段代码时，可能会不知其所以然，因此为了时刻找回当初编程时的思路，建议编写注释。

2. 可读性第一，效率第二。如今软件开发愈发复杂，进行一次开发往往不是一个人的工作，需要整个团队协同作战，团队队员之间就需要互相阅读他人的代码，编写注释就是为了能让他人更好更快地理解自己所编写的代码。其次，在后期维护时，仍然可以通过注释来掌握理解程序。从某种角度来说，这同样也提高了团队开发的效率。

3. 代码即文档！开发人员编写的源代码也是文档的一部分，我们要把软件里最重要的文档——源代码写规范。

在Java中注释有三种：

1. 单行注释：    //后面跟上注释内容。
2. 多行注释：    /*  中间跟上注释内容 。。。。。*/  
3. 文档注释： /**  。。。注释内容。。。*/

这里多行注释和文档和注释很相似，他们的目的就是为了javadoc程序自动生成文档。

添加注释的原则

代码注释是程序设计者和程序阅读者之间的桥梁，让别人更加容易看懂代码，使团队开发合作大大提高效率，也是程序代码维护性的重要环节之一。所以注释也有原则需要遵守：

1.注释形式统一

在整个应用程序中，使用具有一致的标点和结构的样式来构造注释。如果在其他项目中发现他们的注释规范与这份文档不同，那就按照这份规范写代码，不要试图在继承的规范系统中引入新的规范，以免导致冲突。

2.注释内容要求

内容简单、明了、含义明确，防止注释的多义性、不免错误的注释出现。

注释可以添加的位置

注释可以添加在程序的任意位置，但是我们还是要选择合适的地方插入。一般是添加在类和方法上。

  插图：

注释当中可能出现的东西，即java doc标记：

@author ——》开发该类模块的作者，可以多次使用，指明多个作者，每个坐着之间使用逗号（，）分开。

@version——》该类模块的版本，也可以使用多次，但只有第一次有效。

@see——》参考转向，相关的主题

@param对方法中某参数的说明

@return 对方法返回值的说明

@exception 对方法可能抛出的异常进行说明

把注释生成文档的方式

比如用eclipse生成文档：

1、选中要生成文档的类，右键选择Export

2、在弹出框中选择javadoc

3、左侧选择目录，右侧选中要生成文档的类，中间选则public（只有public修饰类和方法可以生成文档）；中下这里选中要把文档放的位置。

4、接着点击finish，找到生成文档存放的地方，用浏览器打开