Makefileのドキュメンテーション

Makefileもある程度大きくなると、ドキュメントが必要になります。JavadocやEDocのように、ドキュメンテーションコメントから文書を生成してくれるツールがないかな？ -- たいした要求は持ってなかったので、とりあえず作ってみました。

仕様は単純です。

1. #*からはじまる行はドキュメンテーションコメントとみなす。
2. 出現した#*の次の行が変数定義、またはifdef/ifndef行なら、コメントは変数の説明とみなす。
3. 出現した#*の次の行がルールなら、コメントはターゲットの説明とみなす。
4. それ以外の場合は、コメントは見出しとみなす。

いまのところ、この程度の機能でも間に合っています。（文字エンコーディングがUTF-8と仮定してます。）

プログラムは、滅多に使わないPerlで書いてみました → 別ウィンドウにテキストで表示（文字エンコーディングはUTF-8） 生成したHTML文書の例 → 別ウィンドウに表示

もとになったMakefileの一部を抜粋すると、こんな感じ（↓）です。

… … …
#* 生成された実行可能ファイルを入れるディレクトリ

JS_BIN_DIR :=../js_bin

#* 生成されたドキュメンテーション・ファイルを入れるディレクトリ

JS_DOC_DIR :=../js_doc

#* 各種の開発ツールをまとめてインストールしたディレクトリ

JS_TOOLS_DIR :=../../jstools
… … …
#* Java

#
#* java VM の起動コマンド（引数含まず）

ifndef JAVA

 #* javaがインストールされたディレクトリ

 ifdef JAVA_HOME

  JAVA:=$(JAVA_HOME)/bin/java

 else

  JAVA:=java 

 endif

endif # !JAVA
… … …
#* ターゲット
.PHONY: lint obj doc all skel

#* lint obj doc

all: lint obj doc
#* JSLintによるチェック

lint: $(JsSrcDir)/.lint.timestamp
#* 配布用JavaScriptファイルの作成

obj: $(objects)
#* API文書の作成

doc: $(doc_index)
… … …