JavaDoc那些事儿

让程序员写一千行代码容易，要让他写一千字的文档就难了。

如果在代码中按照约定写一些注释，代码完成时相对应的文档就会自动生成就好了。

JavaDoc就是这么一个工具（在JDK/bin下可以找到），它从源代码中抽取类、方法、成员等注释形成一个与源代码配套的API文档。大家阅读的Java官网API和Android官网API就是用此技术来完成的。

大家可以尝试用命令行：javadoc -help 来看看它的指令。

做文档是一个细致活，所以它提供了相当多的参数。使用容易，要用好就比较难了，这要经常去实践。本文就当是抛砖引玉了。

特殊的注释与标示

/**...*/是javadoc专用注释，在这个注释里可以用@来标示一些特殊变量，请看下面：

关键字	作用
@author	作者信息
@version	版本
@param	参数
@since	最早使用的版本
@return	返回值
@throws	异常类或抛出条件
@deprecated	不推荐使用警告
@see	交叉参考

实践一下

把上一篇文章中的两个util类做下doc处理，请看：

package linc.util;
/**
 *linc.util.Print.java,for test jar and javadoc.
 *@author linc
 *@version 1.0
 *@see linc.util.Log
 */
public class Print
{
	/**
	 * print function, for once.
	 */
	public void printOnce(String msg)
	{
		System.out.println("linc:" + msg);
	}
	/**
	 * print function, for twice.
	 */
	public void printTwice(String msg)
	{
		for(int i =0;i<2;i++)
		{
			printOnce(msg);
		}
	}
}

package linc.util;
/**
 * print log
 * @author linc
 * @version 1.0 
 */
public class Log
{
	/**
	 * print debug log
	 * @param msg : what print msg you want.
	 */ 
	public void debug(String msg)
	{
		System.out.println("Debug:" + msg);
	}
	/**
	 * print info log
	 * @param msg : print msg what you want.
	 */ 
	public void info(String msg)
	{
		System.out.println("Info:" + msg);
	}
}

如果我们只是简单把上面两个类javadoc做成HTML格式的文档，命令行中输入：

D:\workspace\Java\test-jar2\src>javadoc Print.java Log.java
正在装入源文件 Print.java...
正在装入源文件 Log.java...
正在构造 Javadoc 信息...
标准 Doclet 版本 1.6.0_10
正在构建所有软件包和类的树...
正在生成 linc/util/\Log.html...
正在生成 linc/util/\Print.html...
正在生成 linc/util/\package-frame.html...
正在生成 linc/util/\package-summary.html...
正在生成 linc/util/\package-tree.html...
正在生成 constant-values.html...
正在构建所有软件包和类的索引...
正在生成 overview-tree.html...
正在生成 index-all.html...
正在生成 deprecated-list.html...
正在构建所有类的索引...
正在生成 allclasses-frame.html...
正在生成 allclasses-noframe.html...
正在生成 index.html...
正在生成 help-doc.html...
正在生成 stylesheet.css...

运行index.html，结果类似下面：

linc.util 
类 Log
java.lang.Object
  linc.util.Log

--------------------------------------------------------------------------------

public class Logextends java.lang.Objectprint log 

--------------------------------------------------------------------------------

构造方法摘要 
Log() 
            
  方法摘要 
 void debug(java.lang.String msg) 
          print debug log 
 void info(java.lang.String msg) 
          print info log 
  从类 java.lang.Object 继承的方法 
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait 
  
构造方法详细信息 

Log
public Log()方法详细信息 

debug
public void debug(java.lang.String msg)print debug log 

参数：
msg - : what print msg you want.

--------------------------------------------------------------------------------
info
public void info(java.lang.String msg)print info log 

参数：
msg - : print msg what you want.

好的文档习惯是程序员的基本素质，希望大家不要嫌麻烦，清晰的文档会打造出透亮的未来！