<转>为所有到处的API做文档注释（大牛们做JAR包的时候需要做好的事情哦）

我们如何好的生成规范的API文档，我们就要使用JAVADOC哦。要自己手动去写API的也不介意哈。不过我觉得一个核心框架一定要写好注释做好包。这个就是绝对的经典。做好质量和友善的规范，估计用户才会很好使用您努力汗水的结晶。

为了正确的编写出来API文档，你必须在每个被导出的类，接口，方法和域声明做好文档注释。

每个方法的文档应该清晰的描述他与客户的关系以及之间应该遵守的约定。但是也有例外的，除了那种专门被用来继承设计的方法可以脱离这样的约定，但是要告诉这个方法是做什么的，怎么做的就可以不用说了。我们在写方法文档注释时，一定要列举出来前置条件和后置条件，所谓前置条件就是用户能够调用这个方法应该满足的条件。后置条件是当方法调用完成后，哪些条件必须满足。

/**
     * Return the DataSource to use for retrieving Connections.
     * <p>This implementation returns the passed-in DataSource as-is.
     * @param originalDataSource the DataSource as configured by the user
     * on LocalSessionFactoryBean
     * @return the DataSource to actually retrieve Connections from
     * (potentially wrapped)
     * @see LocalSessionFactoryBean#setDataSource
     */
    protected DataSource getDataSourceToUse(DataSource originalDataSource) {
        return originalDataSource;
    }

这样代码绝对值得学习（spring2.5-src.jar）

我正在朝这样的方向去实现，努力让一个年轻人变成大神。5555大神。要的是一种态度和精神，中国不少程序员缺乏的就是这样态度。

这个还有一点需要注意下，我们的方法如果有副作用我们也应该好好注释出来，这点很重要的。例如：这个方法有线程安全问题。比如说他开启了另外一个后台线程。你应该在注释中告诉用户。

*在整个文档注释中采用都是HTML元素，所以比如说特殊符号要使用转义字符。比如“<”使用$lt;等。还有在文档描述的第一句话内部不要使用句号，因为句话会让第一句话直接结束掉。比如：“a is b new object,b.admin create by ”这样的只能产生"a is b new object,b".

要用就用转义字符吧”&#46“.

说了这么多如何使用javadoc生成标准的注释API。简单就用eclipse吧方法如下：

使用eclipse生成文档（javadoc）主要有三种方法：
1，在项目列表中按右键，选择Export（导出），然后在Export(导出)对话框中选择java下的javadoc，提交到下一步。
在Javadoc Generation对话框中有两个地方要注意的：
javadoc command:应该选择jdk的bin/javadoc.exe
destination:为生成文档的保存路径，可自由选择。
按finish(完成)提交即可开始生成文档。
2，用菜单选择：File->Export(文件－>导出)，
剩下的步骤和第一种方法是一样的。
3，选中要生成文档的项目，然后用菜单选择，
Project->Generate Javadoc直接进入Javadoc Generation对话框，剩余的步骤就和第一种方法在Javadoc Generation对话框开始是一样的。

看了说明鬼都会生成API啦呵呵。