Arch-05-01-JavaDoc注释生成文档(java)

使用eclipse生成文档（javadoc）主要有三种方法：
1、在项目列表中按右键，选择Export（导出），然后在Export(导出)对话框中选择java下的javadoc，提交到下一步。
     在Javadoc Generation对话框中有两个地方要注意的：
     （1）javadoc command:应该选择jdk的bin/javadoc.exe
     （2）destination:为生成文档的保存路径，可自由选择。

     （3）在第三个对话框的"Extra Javadoc options" 文本框里面加上-encoding UTF-8 -charset UTF-8

     按finish(完成)提交即可开始生成文档。
2、用菜单选择：File->Export(文件－>导出)，剩下的步骤和第一种方法是一样的。
3、选中要生成文档的项目，然后用菜单选择，Project->Generate Javadoc直接进入Javadoc Generation对话框，

 

     剩余的步骤就和第一种方法在Javadoc Generation对话框开始是一样的。

 

 

简单漂亮的 javaDoc 生成器

 

http://code.google.com/p/doclava/wiki/GettingStarted

 

 

让开发自动化: 文档化一键通

 

http://www.ibm.com/developerworks/cn/java/j-ap06108/

-使用 UMLGraph 生成当前源代码的 UML图。

-使用 SchemaSpy 创建 实体关系图（ERD），归档数据库中的表格和关系。
-使用 Grand 生成构建目标以及它们之间的关系的 Ant 构建图。
-使用 Doxygen 生成 源代码文档。
-使用 DocBook 制作 用户文档。

 

安装手记

 

1. UMLGraph

 

 （1） 下载 http://www.umlgraph.org/download.html。 后来发现，在 windows 和 maven 环境下，其实不用下载，即使下载了，在 pom.xml 文件中配置 <docletPath>D:\path\to\UmlGraph.jar</docletPath> 也失败，总是提示找不到 org.umlgraph.doclet.UmlGraphDoc

 

 （2）pom.xml 中配置

 

 

<project...>

...

<build>
		<plugins>
			<plugin>
				<groupId>org.apache.maven.plugins</groupId>
				<artifactId>maven-site-plugin</artifactId>
				<version>3.0-beta-2</version>
				<configuration>
					<reportPlugins>
						<plugin>
							<groupId>org.apache.maven.plugins</groupId>
							<artifactId>maven-javadoc-plugin</artifactId>
							<version>2.7</version>
							<configuration>
								<charset>UTF-8</charset>
								<encoding>UTF-8</encoding>
								<docencoding>UTF-8</docencoding> 
								<show>private</show>

								<doclet>org.umlgraph.doclet.UmlGraphDoc</doclet>
								<!--<docletPath>/path/to/UmlGraph.jar</docletPath>-->
								<docletArtifact>
									<groupId>org.umlgraph</groupId>
									<artifactId>doclet</artifactId>
									<version>5.1</version>
								</docletArtifact>
								<useStandardDocletOptions>true</useStandardDocletOptions>
								<additionalparam>
	               -inferrel -inferdep -quiet -hide java.* -collpackages java.util.* -qualify -operations 
	               -postfixpackage -nodefontpackagename SimSun 
	               -outputencoding UTF-8
          	  	</additionalparam>
							</configuration>
						</plugin>
					</reportPlugins>
				</configuration>
			</plugin>
		</plugins>
	</build>

</project>

 

 (3) Apache maven 要升级到 maven 3

 

 (4) 有问题 

使用过程中发现这样的问题，就是用ant生成javadoc时，只能在package页中嵌入UNL图表，而每一个具体的类页面中却不能实现嵌入，这是为什么呢？
http://hanqunfeng.iteye.com/blog/869576

     解决办法：下载文件 http://dl.iteye.com/topics/download/1512325c-8259-34ca-ba7e-b103e5ee04bd 直接放入 maven 库中，repository\org\umlgraph\doclet\5.1 ，将名称改成 doclet-5.1.jar。

 

（5）在 pom.xml 目录下执行 dos 命令，mvn site，将会生成文档到 target 的 site 下面。

 

 

2. SchemaSpy

 

    (1) 下载 http://schemaspy.sourceforge.net/

    (2) maven 和 ant 都配置麻烦，maven 捣鼓了很久也没搞定，干脆一句命令行搞定：

java -jar schemaSpy.jar  -t pgsql -u develop -p pass -o   temp -host  devdb.plusns.com -port 5432 -db  mysns  -cp postgresql.jar  -charset UTF-8 -schemas "community,user"

3. Maven Site 站点管理文档一网打尽

 （1）升级 maven3

 （2）父子工程，只需配置父站点中的 /src/site/site.xml...，要配置子工程的 site.xml ，一样的方法，直接放进去。以下为父工程配置 

    /pom.xml

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/maven-v4_0_0.xsd">
...
  <modules>
		<module>base-cache-framework</module>
		...
   </modules>  
   
  <distributionManagement>
		<snapshotRepository>
			<id>archiva.snapshots</id> 
			<name>Internal Snapshot Repository</name> 
			<url>dav:http://archiva.plusrun.cn:8080/archiva/repository/snapshots</url> 
			<uniqueVersion>false</uniqueVersion>
		</snapshotRepository>
    <site>
      <id>apisite</id>
      <url>scp://192.168.1.21/usr/local/tomcat/webapps/mvnsites/</url>
    </site>
  </distributionManagement>
   
  <build>
  	...
		<plugins>
			...
			<plugin>
				<groupId>org.apache.maven.plugins</groupId>
				<artifactId>maven-site-plugin</artifactId>
				<version>3.0-beta-2</version>
        <dependencies>
          <dependency><!-- add support for ssh/scp -->
            <groupId>org.apache.maven.wagon</groupId>
            <artifactId>wagon-ssh</artifactId>
            <version>1.0</version>
          </dependency>
        </dependencies>
				<configuration>
          <locales>zh_CN</locales>  
          <outputEncoding>UTF-8</outputEncoding>  

					<reportPlugins>
            <plugin>
              <groupId>org.apache.maven.plugins</groupId>
              <artifactId>maven-project-info-reports-plugin</artifactId>
              <version>2.2</version>
              <configuration>
                <dependencyDetailsEnabled>false</dependencyDetailsEnabled>
                <dependencyLocationsEnabled>false</dependencyLocationsEnabled>
              </configuration>
              <reports>
                <report>index</report>
                <report>issue-tracking</report>
                <report>license</report>
                <report>modules</report>
                <report>project-team</report>
                <report>scm</report>
                <report>cim</report>
                <report>summary</report>
              </reports>
            </plugin>
						<plugin>
							<groupId>org.apache.maven.plugins</groupId>
							<artifactId>maven-javadoc-plugin</artifactId>
							<version>2.7</version>
							<configuration>
								<charset>UTF-8</charset>
								<encoding>UTF-8</encoding>
								<docencoding>UTF-8</docencoding> 
								<minmemory>1g</minmemory>
						    <maxmemory>1g</maxmemory>
     						<show>private</show>
								<stylesheetfile>src/site/css/stylesheet.css</stylesheetfile>
								<doclet>org.umlgraph.doclet.UmlGraphDoc</doclet>
								<docletArtifact>
									<groupId>org.umlgraph</groupId>
									<artifactId>doclet</artifactId>
									<version>5.1</version>
								</docletArtifact>
								<useStandardDocletOptions>true</useStandardDocletOptions>
								<additionalparam>
	               -inferrel -inferdep -quiet -hide java.* -collpackages java.util.* -qualify -operations 
	               -postfixpackage -nodefontpackagename SimSun 
	               -outputencoding UTF-8
          	  	</additionalparam>
							</configuration>
						</plugin>

						<plugin>
							<groupId>org.apache.maven.plugins</groupId>
							<artifactId>maven-jxr-plugin</artifactId>
							<version>2.1</version>
							<configuration>
								<aggregate>true</aggregate>
							</configuration>
						</plugin>

						<plugin>
							<groupId>org.apache.maven.plugins</groupId>
							<artifactId>maven-surefire-report-plugin</artifactId>
							<version>2.6</version>
						</plugin>
						
						<plugin>
							<groupId>org.codehaus.mojo</groupId>
							<artifactId>cobertura-maven-plugin</artifactId>
							<version>2.4</version>
							<configuration>
								<formats>
									<format>xml</format>
									<format>html</format>
								</formats>
							</configuration>
						</plugin>
						
						<plugin>
							<groupId>org.apache.maven.plugins</groupId>
							<artifactId>maven-checkstyle-plugin</artifactId>
							<version>2.6</version>
						</plugin>

<!--
						<plugin>
							<groupId>org.apache.maven.plugins</groupId>
							<artifactId>maven-pmd-plugin</artifactId>
							<version>2.4</version>
						</plugin>
						
						<plugin>
							<groupId>org.apache.maven.plugins</groupId>
							<artifactId>maven-changes-plugin</artifactId>
							<version>2.1</version>
						</plugin>

						<plugin>
							<groupId>org.apache.maven.plugins</groupId>
							<artifactId>maven-changelog-plugin</artifactId>
							<version>2.1</version>
						</plugin>

            <plugin>
                <groupId>com.wakaleo.schemaspy</groupId>
                <artifactId>maven-schemaspy-plugin</artifactId>
                <version>1.0.4</version>
                <configuration>
                    <databaseType>pgsql</databaseType>
                    <database>plusrun</database>
                    <host>devdb.plusrun.com</host>
                    <user>develop</user>
                    <password>pass</password>
                    <port>5432</port>
                </configuration>
            </plugin>
-->						
					</reportPlugins>
				</configuration>
			</plugin>
  	</plugins>
		
  </build> 
 			
</project>

 

    父工程 /src/site/site.xml

<?xml version="1.0" encoding="UTF-8"?>

<project name="Maven" xmlns="http://maven.apache.org/DECORATION/1.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xsi:schemaLocation="http://maven.apache.org/DECORATION/1.0.0 http://maven.apache.org/xsd/decoration-1.0.0.xsd">

  <bannerLeft>
    <name>软件产品开发 API</name>
    <src>http://mvnsites.plusrun.com/images/mvnsites.png</src>
    <href>http://mvnsites.plusrun.com/</href>
  </bannerLeft>
  <bannerRight>
    <src>http://maven.apache.org/images/maven-small.gif</src>
  </bannerRight>
  <body>
    <links>
      <item name="业主网" href="http://mvnsites.plusrun.com/yeazhu.com" />
    </links>

    <menu name="软件开发产点">
      <item name="介绍" href="index.html"/>
      <item name="在线演示" href="demo.html"/>
      <item name="发布说明" href="release-notes.html" />
      <item name="路线图" href="roadmap.html" />
      <item name="FAQ" href="faq.html"/>
    </menu>

    <menu ref="reports"/>
  </body>
</project>

 

子工程 /yeazhu-web/src/site/site.xml

<?xml version="1.0" encoding="UTF-8"?>

<project name="Maven" xmlns="http://maven.apache.org/DECORATION/1.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xsi:schemaLocation="http://maven.apache.org/DECORATION/1.0.0 http://maven.apache.org/xsd/decoration-1.0.0.xsd">

  <bannerLeft>
    <name>软件产品开发 API</name>
    <src>http://mvnsites.plusrun.com/images/mvnsites.png</src>
    <href>http://mvnsites.plusrun.com/</href>
  </bannerLeft>
  <bannerRight>
    <src>http://maven.apache.org/images/maven-small.gif</src>
  </bannerRight>
  <body>
    <menu name="工程">
      <item name="介绍" href="index.html"/>
      <item name="返回上级工程" href="http://mvnsites.plusrun.com"/>
    </menu>

    <menu ref="reports"/>
  </body>
</project>