文档生成工具 - 仓颉用户手册

仓颉 API 文档生成工具使用指南

cjdoc 整体介绍

cjdoc 是一个支持仓颉语言的 API 文档生成器。

cjdoc 能提取源文件的全局变量、函数、类、结构体、接口、枚举、扩展等语法的文档注释，并输出 HTML 格式的 API 接口文档。

文档注释介绍

什么是文档注释

文档注释是为自动生成文档而写的注释，它是一种带有特殊功能的注释。 cjdoc 能够识别遵循 cjdoc 风格注释的文档注释。

cjdoc 风格文档注释以 /** 开头、以 */ 结尾，并且当编辑多行注释时，每行要以星号开头。文档注释与一般注释的最大区别在于起始符号是/**而不是/*或//。

/**
 * 这是文档注释
 */

/** 这是文档注释 */

/*
 * 这是一般注释
 */

// 这是一般注释

文档注释格式

cjdoc 的一个文档注释由两部分组成，分别为描述部分和注解部分，描述部分又可分为简要描述和详细描述。不同的写法举例如下：

**说明：**以下写法的描述部分如果需要有换行效果，需要在换行地方加上\n

写法 1：描述部分不分开

/**
 * this is description （描述部分）
 *
 * @param parameter-name explanation （注解部分）
 * @return explanation （注解部分）
 */

写法 2：只有描述部分

/**
 * this is description （描述部分）
 */

写法 3：文档注释只有一行，描述部分不分开

/** this is description （描述部分）*/

写法 4：描述部分分简要描述和详细描述

/**
 * @brief this is brief description （简要描述）
 *
 * this is detailed description （详细描述）
 *
 * @param parameter-name explanation （注解部分）
 */

写法 5：描述部分需要换行，需要在换行地方加上\n

正例:

/**
 * this is description.\n
 * add a new line
 */

html 文档效果:

this is description
add a new line

反例：

/**
 * this is description.
 * add a new line
 */

html 文档效果:

this is description. add a new line

cjdoc 支持的注解

标签	描述	示例
@file	文件描述信息	@file file description
@author	标识作者	@author description
@version	指定版本	@version info
@date	指定日期	@date datetime
@since	标记当引入一个特定的变化时	@since release
@see	指定一个到另一个主题的链接	@see anchor
@brief	标记简要描述	@brief brief description
@param	说明一个方法的参数	@param parameter-name explanation
@return	说明返回值类型	@return explanation
@throws	和 @exception 标签一样	The @throws tag has the same meaning as the @exception tag
@exception	标志抛出的异常	@exception exception-name explanation
@note	标记提示信息	@note note text
@warning	标记告警信息	@warning warning text
@attention	标记需要注意的信息	@attention attention text

以下 3 个注解正式代码中不建议用，但是 cjdoc 也支持:

标签	描述	示例
@todo	标记后续需要做的事	@todo paragraph describing what is to be done
@bug	标记代码中未解决的 bug	@bug bug description
@deprecated	标记过期的用法	@deprecated description

cjdoc 的使用方法

cjdoc -h 查看 cjdoc 工具的命令帮助。下面是几个常用的和配置文件相关的命令。

生成配置文件

cjdoc -g [configName] 生成配置文件模板，如果没有输入 configName ，则默认生成文件名为 Doxyfile 的配置文件
cjdoc [configName] 使用配置文件 configName 生成文档
cjdoc -x [configFile] 将 configFile 和默认配置比较，可以看到当前配置修改了哪些条目

**说明：**若使用-g命令时，configName或Doxyfile已存在，则会生成.bak配置文件以备份旧的配置文件信息，并生成新的默认配置文件configName或Doxyfile。

常用配置选项

建议配置的选项

配置选项	默认值	描述
RECURSIVE	默认 NO，建议配置成 YES	是否递归扫描 INPUT 配置的路径
EXTRACT_ALL	默认 NO，建议配置成 YES	如果配置 NO，只会显示带有文档注释的 API 接口
GENERATE_LATEX	默认 YES，建议配置成 NO	是否生成 latex 文件
INPUT	默认空，不配置默认当前路径	源文件路径
OUTPUT_DIRECTORY	默认空，不配置默认当前路径	文档输出路径

**说明：**若有多个源文件路径，可以在INPUT输入多个路径（文件或目录），以空格相隔，也可以使用INPUT +=添加多个路径

  例1：添加以执行`cjdoc`所在的相对路径
  INPUT = src/spirit/annotation src/spirit/dbconnection src/spirit/util/enum_enhance.cj
  例2：添加绝对路径
  INPUT = /home/project/src/spirit/annotation /home/project/src/spirit/dbconnection /home/project/src/spirit/util
  例3：INPUT += 添加多个路径
  INPUT = src/spirit/annotation
  INPUT += src/spirit/dbconnection
  INPUT += src/spirit/util
  注：若所输入路径是不存在的路径，会在执行 cjdoc 过程中显示：
  warning: source 'xxx' is not a readable file or directory... skipping.

说明：EXCLUDE配置选项可用于从INPUT中排除相应的文件或目录

  例1：
  EXCLUDE = src/spirit/annotation src/spirit/dbconnection src/spirit/util/enum_enhance.cj
  例2：添加绝对路径
  EXCLUDE = /home/project/src/spirit/annotation /home/project/src/spirit/dbconnection /home/project/src/spirit/util
  例3：EXCLUDE += 添加多个路径
  EXCLUDE = src/spirit/annotation
  EXCLUDE += src/spirit/dbconnection
  EXCLUDE += src/spirit/util

其他常用选项

配置选项	默认值	描述
PROJECT_NAME	默认空，可不配	工程名，最后会显示在 html 页面标题上
GENERATE_HTML	默认 YES	生成 html 格式的 API 文档
HTML_OUTPUT	默认 html	html 文件生成在 {OUTPUT_DIRECTORY}/{HTML_OUTPUT} 目录下
EXTRACT_PRIVATE	NO	是否显示属性为 private 的接口
EXTRACT_PROTECTED	NO	是否显示属性为 protected 的接口
EXTRACT_PACKAGE	NO	是否显示属性为 package 的接口
EXTRACT_STATIC	NO	是否显示属性为 static 的接口

执行 cjdoc

cjdoc [configName]

使用配置文件 configName 生成 API 文档。如果没有指定 configName，默认使用当前目录下文件名为 Doxyfile 的配置文件，configName文件可以命名为任何 linux 支持的文件名。

注意事项

Windows 版本不支持中文路径，如需对路径中包含中文的源码文件生成 API 文档，请使用 Linux 版本。