Spring – Java/J2EE Application Framework 参考手册

现在的项目中要用到标识符的生成，早就看到Apache上面Jakarta项目的common子项目下有一个id子子项目(^_^，这就是apache)，使用它很容易的就可以完成唯一的标识符的生成。今天稍微花了一点时间试验了一下，很容易就搞定了，基本没碰到什么困难。主要的步骤如下：

1. 下载Apache-common-id。因为这个sub-sub-project是属于sandbox（沙盒中的项目用户可以自由使用，但是这些项目的维护并不得到保证，很可能会一直处于目前的状态）中的一个项目，所以没有binary的下载。只能下载源代码以后编译得到。我是使用Eclipse中的cvs的客户端访问apache的cvs得到的源代码。cvs站点名称为cvs.apache.org，访问路径为/home/cvspublic，用户名为anoncvs，不需要密码。登录到cvs服务器上后检出id项目的所有相关文件。
2. 使用ant对源代码进行编译。我开始用Eclipse里面自带的ant进行编译，但是build失败了。编译器报错说我的jre中的类库版本号与需要的版本号不一致（需要的是48.0版的，我用的J2SE5.0，那个类库的版本号显示是49.0）。我满试了一下不用Eclipse里面自带的ant，自己下载一个ant对源代码编译，结果通过编译了居然（编译的时候ant会根据那个build.xml文件从网上下载相关的类库，所以需要连接到Internet才可以成功）。
3. 然后后面的工作就很轻松了，用jar把编译后的class打包就可以了。
4. 打包好后就可以很容易的使用了。一行代码就可以生成数字字符混合的id号。

以下是参考的一些文章:

1. How to Write Doc Comments for the Javadoc Tool
2. javadoc，在 Java 的注释上做文章
3. 在java源码中为Javadoc编写文档注释(1)

　　在java编码规范中，提到了文档注释可被javadoc用来生成API文档。具体的写法，另有说明。下面是学习笔记，主要是摘了一些值得注意的要点。

1、javadoc的获取

只能从相应的JDK中取得，安装后在bin目录下。具体如下：
* Javadoc 1.4 is included in Java 2 SDK, Standard Edition v 1.4
* Javadoc 1.3 is included in Java 2 SDK, Standard Edition v 1.3
* Javadoc 1.2 is included in Java 2 SDK, Standard Edition v 1.2
* Javadoc 1.1 is included in JDK 1.1

2、文档注释编写(principles)

• Java平台API文档由源码中的文档注释定义，且任何此类文档皆从此类注释取得
• Java平台API文档是调用者(caller)和实现之间的契约(contract)
• 除非另有说明，Java平台API文档声明(assertion)应为与具体实现无关(implelementation-independent)
• Java平台API文档应有足够的声明，以使得软件质量保证部门能写出完全的JCK (Java Compatibility Kit)测试。

3、文档注释编写细则

1. 每个文档注释的第一句，应是个概要句，简明但无遗地描述API项。第一句在第一个后跟空格的点号前结束。当句中出现非结束意义的点加空格时，需要空格进行转义，如 等。
3. 自动重利用父类/接口方法（method）的注释，当（1）一个类方法重写(override)父类的方法时，或（2）一个接口方法重写父接口的方法时，或（3）一个类方法实现一个接口方法时。如果当前方法没文档注释，则从父方法复制，如果有，则不复制而是前两者有小标题 “Overrides”,后者有”Specified by”.
4. 用<code>…</code>来标注关键词或名字
5. 节约使用行内链接{@link}
6. 对方法和构建函数的说明，要去掉括号
7. 可以为了简短使用短语而不是句子
8. 使用第3人称而不是第2人称
9. 以一个动词短语开始对一个方法的描述
10. 对类/接口/字段(field)的描述，可以忽略主语
11. 用”this”而不是“the”来引用从当前类生成的对象
12. 不要仅是简单地把API名字里的单词展开来做描述，要增加一些信息。
13. 当作用”field”一词时，注意它易引起混淆
14. 避免拉丁语缩写
15. 标签顺序
    1. @author，多个作者时按参考修改代码的年代为序
    2. @version
    3. @param，多个参数时以方法声明中的顺序为序，单个@param后跟参数名（不要相应的类型），再加描述
    4. @return
    5. @exception，多个异常时以异常名字的字母顺序为序
    6. @see，多个参见时据 #field,#Constructor(Type, Type…),#Constructor(Type id, Type id…),#method(Type, Type,…),#method(Type id, Type, id…),Class,Class#field,Class#Constructor(Type, Type…),Class#Constructor(Type id, Type id),Class#method(Type, Type,…),Class#method(Type id, Type id,…),package.Class,package.Class#field,package.Class#Constructor(Type, Type…),package.Class#Constructor(Type id, Type id),package.Class#method(Type, Type,…),package.Class#method(Type id, Type, id),package排序
    7. @since
    8. @serial
    9. @deprcated
16. ＠param和@return(当返回不是void时)都是必须的