doxygen-js

用doxygen来注释javascript

English version

doxygen里有提到用perl脚本直接从js代码里获取相应的函数啊类啊的定义的；jsdoc使用rhino来分析js然后生成文档。前者不够灵活容易误判，后者功能太弱和doxygen比起来差的太远，因此我更倾向于用伪码的方式来注释javascript，本文就是介绍怎么用java作为伪码来为javascript写doxygen注释文档。

首先是一个脚本，builddoc（见文末），用来把所有js文件里的伪码和注释弄出来交给doxygen来解释，其实这个脚本很简单，就是把文档中以’///’和’/**’和’/* ‘和’ * ‘和’ */’和’//*’开头的行弄出来并把’//*’给去掉后生成一个同名的.java文件 然后让doxygen去解析目录下的所有.java文件

这样 一个js文件例如

//* package ns;
/**
 * Foo.
 * @param foo foo.
 */
var foo=function(foo){}
//* public void foo(String foo);

就会变成

package ns;
/**
 * Foo.
 * @param foo foo.
 */
public void foo(String foo);

接着按java语法解析这个就可以生成文档了

doxygen的configfile里需要用FILE_PATTERNS = *.java来指明解析目录下所有的.java文档

builddoc：

#!/bin/bash

DIRs="./"

if [ $# -ne 0 ]
then
    DIRs=$@
fi

for DIR in $DIRs; do

    JSs=`find $DIR -name "*.js"`

    for JS in $JSs; do
        DOC=`echo $JS|sed 's/\(.*\)\.js/\1.java/g'`;
        if [ $JS -nt $DOC ]; then
            echo "rebuild $DOC"
            grep -e '^\s*\(///\|//\*\|/\*\*\| \* \| \*/\)' $JS | sed 's/^\s*\/\/\*\(.*\)$/\1/g'> $DOC
        fi
    done

done