自定义doclet编写

         因为对外提供接口需要维护接口文档，但是文档维护一直是成本很高的事，通常是忙着赶项目想着等项目结束之后再补。但是通常是忙过这一阵子就可以------忙下一阵了。so 就一直会被调用方或者测试拉住问这个接口是干啥的呀，这个参数是什么意思啊，交流成本很大。很早就想到了用javadoc来实现，但是javadoc定制行太差，我只想针对某个包下的某些java文件进行doc处理。标准的doclet貌似不能做到，或者要配置一堆的参数很不灵活。我们希望达到能指定某个文件，比如有特定标注的文件生成接口文档，否则类太多了，这个文档也看不了。

       看了下javadoc的介绍，发现只要符合一定的标准就行还不用实现接口，比如只要有方法

 public static boolean start(RootDoc root) 

那么这个类就可以成为自定义的doclet。可是在实际使用中发现这有个坑，如果只有这个方法，那么你只能使用javadoc 规定的参数，但是不能使用sun 标准的doclet 参数比如指定输出目录 -d 这个参数。然后比较了下sun的HtmlDoclet的源码发现只要增加下面2个方法就可以。

 public static int optionLength(String option) {
        // Construct temporary configuration for check
        return (ConfigurationImpl.getInstance()).optionLength(option);
    }

public static boolean validOptions(String options[][], DocErrorReporter reporter) {
        // Construct temporary configuration for check
        return (ConfigurationImpl.getInstance()).validOptions(options, reporter);
    }

ok，回到我们的需求，我们想针对特定的注解类进行doc处理，但是输出html文件又不想自己干这事。所以首先想到的是仿照HtmlDoclet 写一个自己的doclet，然后写的时候发现很多操作在父类AbstractDoclet中，而且sun写的代码压根没扩展性，我想改写点东西基本办不到，没办法把这个父类也复制下来搞一遍。发现很多操蛋的地方，他把RootDoc里的一些数据解析定义在Configuration 里面，有时候又使用RootDoc，有时候使用Configuration 。只能跟着代码大致修改，有时候结果跟想象的又不一样就要一遍遍的调试。比如过滤掉没有需要生成doc的类所在的package。解析这部分改好之后发现输出的html文件太复杂了，达不到我们的要求，因此又把FrameOutputWriter 弄下来改一改。这下总算api 文档能稍微简单赶紧一点了。然后配置下maven的pom文件让javadoc在打包的时候自动生成html文件到web目录下，这样应用起来之后就可以通过特定的目录访问了

 <plugin>
                <groupId>org.apache.maven.plugins</groupId>
                <artifactId>maven-javadoc-plugin</artifactId>
                <version>2.8</version>
                <configuration>
                    <subpackages>you package name1 :you package name2 </subpackages>
                    <outputDirectory>${basedir}/src/main/webapp/apidocs</outputDirectory>
                    <reportOutputDirectory>${basedir}/src/main/webapp/apidocs</reportOutputDirectory>
                    <doclet>com.**.**.MyHtmlDoclet</doclet>
                    <docletArtifact>
                        <groupId>***.***.***</groupId>
                        <artifactId>***</artifactId>
                        <version>1.10-SNAPSHOT</version>
                    </docletArtifact>
                    <useStandardDocletOptions>true</useStandardDocletOptions>
                    <encoding>UTF-8</encoding>
                    <docencoding>GBK</docencoding>
                    <breakiterator>true</breakiterator>
                    <keywords>true</keywords>
                    <show>private</show>
                </configuration>
                <executions>
                    <execution>
                        <id>attach-javadocs</id>
                        <phase>prepare-package</phase>
                        <goals>
                            <goal>javadoc</goal>
                        </goals>
                    </execution>
                </executions>
            </plugin>

注意这里要用docletArtifact 指定自定义doclet所在的maven二方包，就近找个工程提供的client包把代码放进去打个包就ok了。

最后附上源码，MyHtmlDoclet 就是自定义的源码。

http://download.csdn.net/detail/ykdsg/5171078

大家可以从这里下载