背景

ドキュメントジェネレータとは、Markdown ソースや、指定の文法で記述されたコメントアウトなどから、プログラムのドキュメントを生成してくれるものです。

出力ドキュメントフォーマットは Web (HTML) だったり TeX だったり PDF だったり、ものによって対応は様々。(だいたい HTML はきちんと対応している印象)

ここでは後者「コメントアウトから、プログラムのドキュメント」について扱います。

言語	ジェネレータ
C/C++ など	Doxygen
JavaScript	JSDoc
Python	Sphinx (Docstring)

ちなみに Markdown → Web のジェネレーターは GitBook や Docsify などがある。

特に Doxygen と JSDoc については、@... というコマンドを書く特徴がよく似ています。ただ、コマンドが全く同じではないため、「どっちが何だっけ･･･」と混合してしまうことがしばしば。

というわけで、引数や返り値など、主なコマンドの対応一覧を作成することにしました。

Docstring は Google スタイルを考えます。

(ちなみに、これらの言語は自分がよく使うというだけの選びです。)

一覧

次のように表記します。

変数名を書く箇所: name
型名を書く箇所: type
スペース: _

内容	Doxygen	JSDoc	Sphinx (Docstring)
簡易説明	`@brief`	`@summary` (タグ省略可)	最初の `"""` の行
詳細説明	`@details`	`@description` (タグ省略可)	最初の `"""` に 1行空けた次
ノート	`@note`	規定なし	`Note:`
引数	`@args[in] name` `@args[out] name`	`@param {type} name`	`Args:` `__name (type):`
返り値	`@return`	`@returns {type}`	`Returns:` `__type:`
メンバ変数	詳細後述	詳細後述	`Attributes:` `__name (type):` (Args と同じ文法)
コード例	詳細後述	`@example`	`Example:`
作者	`@author`	`@author`	規定なし

※ 表記方法が複数ある場合もありますが、1つのみ掲載

Doxygen のコード例記述について

@example というタグがありますが、JSDoc、Sphinx と違い、ここにはコード例の書かれたソースファイル名を指定します。(@example func_sample.c というように。)

コードブロック上に直接コード例を書きたいときは、代わりに @code が使えます。(記述例を参照)

メンバ変数の記述について

Doxygen、JSDoc では、いずれもメンバの宣言の上にドキュメントを記せばタグ不要です。

class AnyClass {
  private:
  /**
   * @brief Member description
   */
  int member;
};

class AnyClass {
  /**
   * @summary Member description
   */
  #member;
}

Doxygen における @fn (関数説明)、@var (変数説明) も同様で、関数定義の真上に書けばタグ不要です (下の記述例のように)。

@fn については、必須なときだけ使ってほしいと公式ドキュメントにあります。

プライベートメンバ・メソッドは、デフォルトでドキュメント出力されません。出力させるには、設定の変更またはビルド時にオプションが必要です。

JSDoc では、スタティックメンバには @memberof ClassName を追加で書きます。そうすると、ドキュメントに static として表示してくれます。(JSDoc 4.0.2 で動作確認)

class AnyClass {
  /**
   * @summary Member description
   *
   * @memberof AnyClass
   */
  static member = 2;
}

なお、スタティックメソッドは追加の記述無しでも static として表示してくれます。(何で･･･？)

記述例

Doxygen (C/C++)

/**
 * @file func.c
 * ↑これ無しだとデフォルトでドキュメント化されない
 *
 * @brief Source file description
 *
 * @details
 * Source file detail description
 *
 * @author aKuad
 */

/**
 * @brief Function description
 *
 * @details
 * Function detail description
 * 
 * Example:
 *
 * @code
 * int res = func(3);
 * // 3
 * @endcode
 *
 * @note
 * Note of function
 *
 * @param[in] arg Argument description
 * @return Return description
 */
int func(int arg) {
  return arg;
}

ドキュメント表示例:

スクリーンショット

JSDoc

/**
 * @file Source file description
 * ↑トップページへの表示に必要
 *
 * @description
 * Source file detail description
 *
 * @author aKuad
 */

/**
 * @summary Function description
 *
 * @description
 * Function detail description
 *
 * @example
 * res = func(3);
 * // 3
 *
 * @param {number} arg Argument description
 * @returns Return description
 */
function func(arg) {
  return arg;
}

ドキュメント表示例:

スクリーンショット

@file 横の概要記述 (または @summary) と @description を同時に記述すると、@description しか反映されないようです。(JSDoc 4.0.2 で動作確認)

@summary と @description の表示の違いは特に見られないようです。

docstring

"""Source file description

Source file detail description

"""

def func(arg: int):
  """Function description

  Function detail description

  Example:
    Examples here::

      ret = func(3)

  Note:
    Note of function

  Args:
    arg(int): Argument description
  
  Return:
    int: Return description

  """
  return arg

ドキュメント表示例:

スクリーンショット

付録 - 全タグ一覧

Doxygen タグ一覧

JSDoc タグ一覧 (トップページ)

Docstring セクション一覧

付録 - ビルドコマンド例

Doxygen

sudo apt install doxygen

ls
# func.cpp

doxygen -g
ls
# Doxyfile  func.c

vim Doxyfile
# 任意のエディタで各種設定をする
# 出力先の指定は
#   OUTPUT_DIRECTORY       = ./docs
# クラスのプライベートメンバも出力するには
#   EXTRACT_PRIVATE        = YES

doxygen
ls
# Doxyfile  func.c  docs
# ./docs/html に HTML ページが生成される

JSDoc

npm install -g jsdoc

ls
# func.js

jsdoc -d docs *
# クラスのプライベートメンバも出力するには -p を付与
#   jsdoc -p -d docs *

ls
# func.js  docs
# ./docs/html に HTML ページが生成される

Sphinx

pip install sphinx

ls
# func.py

sphinx-quickstart docs
# 表示に従って各設定を入力
# ここではビルドディレクトリは分けない設定で

ls
# func.py  docs

vim docs/conf.py
# 任意のエディタで各種設定をする, 以下は最低限でも必須
# パス追加
#   import os, sys
#   sys.path.insert(0, os.path.dirname('../'))
# 拡張の追加
#   extensions = ['sphinx.ext.autodoc', 'sphinx.ext.napoleon']

cd docs
sphinx-apidoc -f -o ./ ../
# クラスのプライベートメンバも出力するには -P を付与
#   sphinx-apidoc -f -P -o ./ ../
sphinx-build ./ ./_build/

# ./docs/_build に HTML ページが生成される