Hello World

POM中引入插件

<build>
    <plugins>
        <plugin>
            <groupId>org.apache.maven.plugins</groupId>
            <artifactId>maven-javadoc-plugin</artifactId>
            <version>2.10.3</version>
            <configuration>
                <doclet>net.winroad.wrdoclet.HtmlDoclet</doclet>
                <docletArtifact>
                    <groupId>net.winroad</groupId>
                    <artifactId>wrdoclet</artifactId>
                    <version>1.2.3</version>
                </docletArtifact>
                <useStandardDocletOptions>false</useStandardDocletOptions><!-- important ! -->
                <additionalparam>
                    -systemname demoSystemName
                    -branchname featureBranchName
                    -charset utf-8 
                    -d .
                </additionalparam>
            </configuration>
        </plugin>
    </plugins>
</build>

直接在命令行运行mvn javadoc:javadoc 即可在本地target\site\apidocs目录下生成接口文档，直接点击index.html即可浏览。当然生成的文档还不够详尽，一份完善的接口文档需要足够的注释。wrdoclet主要通过注释来生成文档。这里通过一个简单的例子来看一下效果。

/**
 * 获取用户列表
 * @param name 用户名称
 * @tag 用户管理， 用户展示
 * 
 * @author Adams
 * @version 0.0.1
 * @memo init create
 * 
 * @author Bob
 * @version 0.0.2
 * @memo fix bug
 * 
 * @return 用户列表
 */
@WebResult(name = "getUserResult")
public List<User> getUserList(@XmlElement(required=false) @WebParam(name = "name") String name);

这里需要注意的是代码的注释方式是

/** 
 * ...
 */

不能使用

/*
 * ...
 */

或者

// ...

否者javadoc无法获取注释内容。

下面就是不符合规范的例子

// 悲催，这种注释doclet不认
// 添加课程
// @tag Clazz, School, OPS
// @author Adams
// @version 0.0.1
// @memo init create
// @author Bob
// @version 0.0.2
// @memo fix bug
@RequestMapping(value = "/class/add", method = RequestMethod.POST)
public @ResponseBody
Clazz addClass(@RequestBody Clazz clazz, HttpServletRequest httpRequest,
        HttpServletResponse httpResponse) {
    return clazz;
}