API 文档生成工具

功能简介

cjdoc(Cangjie Doc) 是一个支持仓颉语言的 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 支持的注解

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

使用说明

使用cjdoc -h 查看 cjdoc 工具的命令帮助。

Doxygen version 1.9.3 (cd5f678d1ce70159572e23563d4e21735e8dfe29*)
Copyright Dimitri van Heesch 1997-2021

You can use doxygen in a number of ways:

1) Use doxygen to generate a template configuration file:
    ./cjdoc [-s] -g [configName]

2) Use doxygen to update an old configuration file:
    ./cjdoc [-s] -u [configName]

3) Use doxygen to generate documentation using an existing configuration file:
    ./cjdoc [configName]

4) Use doxygen to generate a template file controlling the layout of the
   generated documentation:
    ./cjdoc -l [layoutFileName]

    In case layoutFileName is omitted layoutFileName.xml will be used as filename.
    If - is used for layoutFileName doxygen will write to standard output.

5) Use doxygen to generate a template style sheet file for RTF, HTML or Latex.
    RTF:        ./cjdoc -w rtf styleSheetFile
    HTML:       ./cjdoc -w html headerFile footerFile styleSheetFile [configFile]
    LaTeX:      ./cjdoc -w latex headerFile footerFile styleSheetFile [configFile]

6) Use doxygen to generate a rtf extensions file
    ./cjdoc -e rtf extensionsFile

    If - is used for extensionsFile doxygen will write to standard output.

7) Use doxygen to compare the used configuration file with the template configuration file
    ./cjdoc -x [configFile]

8) Use doxygen to show a list of built-in emojis.
    ./cjdoc -f emoji outputFileName

    If - is used for outputFileName doxygen will write to standard output.

If -s is specified the comments of the configuration items in the config file will be omitted.
If configName is omitted 'Doxyfile' will be used as a default.
If - is used for configFile doxygen will write / read the configuration to /from standard output / input.

If -q is used for a doxygen documentation run, doxygen will see this as if QUIET=YES has been set.

-v print version string, -V print extended version information

下面是几个常用的和配置文件相关的命令。

生成配置文件

生成配置文件模板，如果没有输入 configName ，则默认生成文件名为 Doxyfile 的配置文件。

cjdoc -g [configName]

使用配置文件 configName 生成文档。

cjdoc [configName]

将 configFile 和默认配置比较，可以看到当前配置修改了哪些条目。

cjdoc -x [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输入多个路径（文件或目录），以空格相隔， 也可以使用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使用示例

  说明：

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

  例 1：添加以执行cjdoc所在的相对路径。

  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
  

其他常用选项

执行 cjdoc

cjdoc [configName]

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

执行完cjdoc后，在输出路径下生成html格式文档，可在html目录下点击index.html查看文档构建效果。

相关资料

cjdoc 是基于开源工具 doxygen 扩展了仓颉语言。doxygen 本身功能非常庞大，资料丰富，cjdoc 中非语言相关的特性，与 doxygen 是互通的。 doxygen 的参考手册可参照: doxygen 用户手册。