doxygen 初次使用尝试

做项目时，需要看源码和写文档，看源码时，则需要写注释。如果能在注释源码完成后，就能生成对应的文档，可以减少很多工作。 

使用doxygen可以实现这个功能（由于其主要用于C++，Java等，对JavaScript的支持可能没有JSdoc 3等好）。不过在注释的时候要使用标准注释方法，可以参考javadoc，即以/**起始，以*/结束

(关于在Sublime Text2快速添加注释的方法，可以安装插件DocBlockr，之后只需输入/**然后按tab键，即可生成注释块)

提供一个测试的例子如下。

/**
 * @description 求两个数的和<br />
 * 1) 参数将强制转换为Number类型<br />
 * 2) 这是一个全局的公用方法
 * @method add
 * @param {Number} num1 数1
 * @param {Number} num2 数2
 * @return {Number} 数1和数2的和
 * @since 2013-08-04
 * @author lee
 */
function add(num1,num2){
	return Number(num1)+Number(num2);
}

之后，关于doxygen的安装与使用方法：

1.安装

可以从如下路径下载doxygen，地址：http://jaist.dl.sourceforge.net/project/doxygen/rel-1.8.9.1/doxygen-1.8.9.1-setup.exe

直接安装即可

2.启动

在开始菜单可以找到

启动界面如下

3.配置

首先STEP1 设立工作空间

之后在STEP2进行具体的配置

配置分为Wizard（向导），Expert（专家）

Wizard（向导）中的内容比较简单，

Expert（专家）中比较详细，在Wizard添加的信息也在Expert中通用

首先配置Wizard->Project

之后Mode中

out中先不用管

Diagrams中选择 No diagrams 

之后在Expert中project，选择输出语言

之后在Input中修改下

如果在FILE_PATTERNS中没有你要识别的文件扩展名，比如.js，则如数*.js,然后点加号添加入识别列表

之后其他的都不管，切换到Run

先执行 Run doxygen ，再Show HTML output，即可看到

然后选文件，

点击js文件即可看到

 

 如上图生成的文档。

关于配置，如果有尝试出什么更好的方法，欢迎留言

关于支持的注释，有如下

转自：http://hi.baidu.com/ecalf830/item/bcf5d88afe82f2814414cf48

　　命令名 描述 

　　@param

　　@argument 指定参数名和说明来描述一个函数参数。 

　　@return

　　@returns 描述函数的返回值。 

　　@author 指示代码的作者。 

　　@deprecated 指示一个函数已经废弃，不建议使用，而且在将来版本的代码中可能会彻底删除。要避免使用这段代码。 

　　@see 创建一个HTML链接指向指定类的描述。 

　　@version 指定发布版本。 

　　@requires 创建一个HTML链接，指向这个类所需的指定类。 

　　@throws

　　@exception 描述函数可能抛出的异常的类型。 

　　{@link} 创建一个HTML链接，指向指定的类。这与@see很类似，但{@link}能嵌在注释文本中。 

　　@author 指示代码的作者。（译者注：这个标记前面已经出现过，建议去掉） 

　　@fileoverview 这是一个特殊的标记，如果在文件的第一个文档块中使用这个标记，则指定该文档块的余下部分将用来提供文件的一个概述。 

　　@class 提供类的有关信息，用在构造函数的文档中。 

　　@constructor 明确一个函数是某个类的构造函数。 

　　@type 指定函数的返回类型。 

　　@extends 指示一个类派生了另一个类。通常JSDoc自己就可以检测出这种信息，不过，在某些情况下则必须使用这个标记。 

　　@private 指示一个类或函数是私有的。私有类和函数不会出现在HTML文档中，除非运行JSDoc时提供了—private命令行选项。 

　　@final 指示一个值是常量值。要记住JavaScript无法真正保证一个值是常量。 

　　@ignore JSDoc 会忽略有这个标记的函数。