経緯
- 以前から一部のリポジトリで phpdoc がメモリ不足で落ちて困っていた
- Doxygen は何年か前にも試していたが、PHP の解釈がイマイチで採用を見送っていた
- 今回試してやはりイマイチだったが、いくつかの問題を我慢すれば使えそうだったので、メモリ不足で落ちるよりマシと判断して使い始めた
現在稼働しているバージョンは 1.5.6
動かせるようになるまで
最初は
- 落ちる
- 返ってこない
ファイルが後を絶たなかった。どうしたか。
EXCLUDE しまくる
まずはこれが基本。設定ファイルの中に EXCLUDE, EXCLUDE_PATTERNS の設定があるのでこれを利用してひたすら問題になるファイルを除外しまくる。話はそれから。
- とりあえず EXCLUDE
- 一つずつコメントやコードの構造を直して落ちないか試す
以上をくり返すことでほとんどのコードを扱えるようになる。
※ Warning はとりあえず無視しして徐々に対応していく。
やばげなパターン
if () {
...
}
でコード全体を囲んでいると doxygen が返ってこなくなりやすいみたい。
とは言え必ず返ってこないかというとそうではなく、コメントの書き方が正しくない場合に返ってこなくなる可能性が高い、という感じらしい。
コメントの書き方ミスにはとても厳しい
phpdoc と違ってかなり厳しい。少なくとも phpdoc 的には大きな問題でなくても Doxygen ではダメなケースは多い。ただし本当に問題になるのはやはり
正しくないコメント
なので、普段からちゃんと書けている場合はとりあえず移行そのものはそれほど大変ではないと思う。
対応してるタグは少ない
phpdoc に比べると対応するタグがだいぶ少ない。ただし、
- シンプルでよいと思うことにする
- ソースにリンクを張れるのである程度解釈が変でも直接読ませることでよしとする
で、乗り越えられる :-)
切り替えて使う
で述べたように phpdoc の生成は自動化しているのだが、この中でドキュメント出力先は都度クリアしてから作業を始めている。このとき削除には
rm -r *
を使っているので、ドキュメント生成先に .doxyfile というファイルが用意されていたら doxygen で、そうでなければ従来通り phpdoc で処理することにした。1
これで、全リポジトリで一気に Doxygen 対応をはかる必要がない。
よさげな設定
いろいろ試行錯誤した結果と default の diff を出してみた。たぶん Java っぽく振るのがいいんだと思ってるんだけど、どうなんだろう。
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| @@ -38,7 +38,7 @@ | |
| # If a relative path is entered, it will be relative to the location | |
| # where doxygen was started. If left blank the current directory will be used. | |
| -OUTPUT_DIRECTORY = | |
| +OUTPUT_DIRECTORY = /PATH/TO/DEST | |
| # If the CREATE_SUBDIRS tag is set to YES, then doxygen will create | |
| # 4096 sub-directories (in 2 levels) under the output directory of each output | |
| @@ -60,7 +60,7 @@ | |
| # Portuguese, Romanian, Russian, Serbian, Slovak, Slovene, Spanish, Swedish, | |
| # and Ukrainian. | |
| -OUTPUT_LANGUAGE = English | |
| +OUTPUT_LANGUAGE = Japanese | |
| # If the BRIEF_MEMBER_DESC tag is set to YES (the default) Doxygen will | |
| # include brief member descriptions after the members that are listed in | |
| @@ -92,7 +92,7 @@ | |
| # Doxygen will generate a detailed section even if there is only a brief | |
| # description. | |
| -ALWAYS_DETAILED_SEC = NO | |
| +ALWAYS_DETAILED_SEC = YES | |
| # If the INLINE_INHERITED_MEMB tag is set to YES, doxygen will show all | |
| # inherited members of a class in the documentation of that class as if those | |
| @@ -105,7 +105,7 @@ | |
| # path before files name in the file list and in the header files. If set | |
| # to NO the shortest path that makes the file name unique will be used. | |
| -FULL_PATH_NAMES = YES | |
| +FULL_PATH_NAMES = NO | |
| # If the FULL_PATH_NAMES tag is set to YES then the STRIP_FROM_PATH tag | |
| # can be used to strip a user-defined part of the path. Stripping is | |
| @@ -129,7 +129,7 @@ | |
| # (but less readable) file names. This can be useful is your file systems | |
| # doesn't support long names like on DOS, Mac, or CD-ROM. | |
| -SHORT_NAMES = NO | |
| +SHORT_NAMES = YES | |
| # If the JAVADOC_AUTOBRIEF tag is set to YES then Doxygen | |
| # will interpret the first line (until the first dot) of a JavaDoc-style | |
| @@ -137,7 +137,7 @@ | |
| # comments will behave just like regular Qt-style comments | |
| # (thus requiring an explicit @brief command for a brief description.) | |
| -JAVADOC_AUTOBRIEF = NO | |
| +JAVADOC_AUTOBRIEF = YES | |
| # If the QT_AUTOBRIEF tag is set to YES then Doxygen will | |
| # interpret the first line (until the first dot) of a Qt-style | |
| @@ -160,7 +160,7 @@ | |
| # If set to NO, the detailed description appears after the member | |
| # documentation. | |
| -DETAILS_AT_TOP = NO | |
| +DETAILS_AT_TOP = YES | |
| # If the INHERIT_DOCS tag is set to YES (the default) then an undocumented | |
| # member inherits the documentation from any documented member that it | |
| @@ -200,7 +200,7 @@ | |
| # Java. For instance, namespaces will be presented as packages, qualified | |
| # scopes will look different, etc. | |
| -OPTIMIZE_OUTPUT_JAVA = NO | |
| +OPTIMIZE_OUTPUT_JAVA = YES | |
| # Set the OPTIMIZE_FOR_FORTRAN tag to YES if your project consists of Fortran | |
| # sources only. Doxygen will then generate output that is more tailored for | |
| @@ -277,17 +277,17 @@ | |
| # Private class members and static file members will be hidden unless | |
| # the EXTRACT_PRIVATE and EXTRACT_STATIC tags are set to YES | |
| -EXTRACT_ALL = NO | |
| +EXTRACT_ALL = YES | |
| # If the EXTRACT_PRIVATE tag is set to YES all private members of a class | |
| # will be included in the documentation. | |
| -EXTRACT_PRIVATE = NO | |
| +EXTRACT_PRIVATE = YES | |
| # If the EXTRACT_STATIC tag is set to YES all static members of a file | |
| # will be included in the documentation. | |
| -EXTRACT_STATIC = NO | |
| +EXTRACT_STATIC = YES | |
| # If the EXTRACT_LOCAL_CLASSES tag is set to YES classes (and structs) | |
| # defined locally in source files will be included in the documentation. | |
| @@ -300,7 +300,7 @@ | |
| # the interface are included in the documentation. | |
| # If set to NO (the default) only methods in the interface are included. | |
| -EXTRACT_LOCAL_METHODS = NO | |
| +EXTRACT_LOCAL_METHODS = YES | |
| # If this flag is set to YES, the members of anonymous namespaces will be | |
| # extracted and appear in the documentation as a namespace called | |
| @@ -352,7 +352,7 @@ | |
| # in case and if your file system supports case sensitive file names. Windows | |
| # and Mac users are advised to set this option to NO. | |
| -CASE_SENSE_NAMES = NO | |
| +CASE_SENSE_NAMES = YES | |
| # If the HIDE_SCOPE_NAMES tag is set to NO (the default) then Doxygen | |
| # will show members with their full class and namespace scopes in the | |
| @@ -450,7 +450,7 @@ | |
| # then setting the SHOW_DIRECTORIES tag to YES will show the directory hierarchy | |
| # in the documentation. The default is NO. | |
| -SHOW_DIRECTORIES = NO | |
| +SHOW_DIRECTORIES = YES | |
| # Set the SHOW_FILES tag to NO to disable the generation of the Files page. | |
| # This will remove the Files entry from the Quick Index and from the | |
| @@ -534,7 +534,7 @@ | |
| # directories like "/usr/src/myproject". Separate the files or directories | |
| # with spaces. | |
| -INPUT = | |
| +INPUT = /PATH/TO/SRC | |
| # This tag can be used to specify the character encoding of the source files | |
| # that doxygen parses. Internally doxygen uses the UTF-8 encoding, which is | |
| @@ -542,7 +542,7 @@ | |
| # into libc) for the transcoding. See http://www.gnu.org/software/libiconv for | |
| # the list of possible encodings. | |
| -INPUT_ENCODING = UTF-8 | |
| +INPUT_ENCODING = EUC-JP | |
| # If the value of the INPUT tag contains directories, you can use the | |
| # FILE_PATTERNS tag to specify one or more wildcard pattern (like *.cpp | |
| @@ -551,13 +551,13 @@ | |
| # *.c *.cc *.cxx *.cpp *.c++ *.java *.ii *.ixx *.ipp *.i++ *.inl *.h *.hh *.hxx | |
| # *.hpp *.h++ *.idl *.odl *.cs *.php *.php3 *.inc *.m *.mm *.py *.f90 | |
| -FILE_PATTERNS = | |
| +FILE_PATTERNS = *.php *.phtml *.inc *.ini | |
| # The RECURSIVE tag can be used to turn specify whether or not subdirectories | |
| # should be searched for input files as well. Possible values are YES and NO. | |
| # If left blank NO is used. | |
| -RECURSIVE = NO | |
| +RECURSIVE = YES | |
| # The EXCLUDE tag can be used to specify files and/or directories that should | |
| # excluded from the INPUT source files. This way you can easily exclude a | |
| @@ -577,7 +577,7 @@ | |
| # against the file with absolute path, so to exclude all test directories | |
| # for example use the pattern */test/* | |
| -EXCLUDE_PATTERNS = | |
| +EXCLUDE_PATTERNS = */.svn/* .svn */selenium/* | |
| # The EXCLUDE_SYMBOLS tag can be used to specify one or more symbol names | |
| # (namespaces, classes, functions, etc.) that should be excluded from the | |
| @@ -647,7 +647,7 @@ | |
| # Note: To get rid of all source code in the generated output, make sure also | |
| # VERBATIM_HEADERS is set to NO. | |
| -SOURCE_BROWSER = NO | |
| +SOURCE_BROWSER = YES | |
| # Setting the INLINE_SOURCES tag to YES will include the body | |
| # of functions and classes directly in the documentation. | |
| @@ -658,7 +658,7 @@ | |
| # doxygen to hide any special comment blocks from generated source code | |
| # fragments. Normal C and C++ comments will always remain visible. | |
| -STRIP_CODE_COMMENTS = YES | |
| +STRIP_CODE_COMMENTS = NO | |
| # If the REFERENCED_BY_RELATION tag is set to YES | |
| # then for each documented function all documented | |
| @@ -729,7 +729,7 @@ | |
| # If a relative path is entered the value of OUTPUT_DIRECTORY will be | |
| # put in front of it. If left blank `html' will be used as the default path. | |
| -HTML_OUTPUT = html | |
| +HTML_OUTPUT = . | |
| # The HTML_FILE_EXTENSION tag can be used to specify the file extension for | |
| # each generated HTML page (for example: .htm,.php,.asp). If it is left blank | |
| @@ -867,7 +867,7 @@ | |
| # releases of Doxygen, the values YES and NO are equivalent to FRAME and NONE | |
| # respectively. | |
| -GENERATE_TREEVIEW = NONE | |
| +GENERATE_TREEVIEW = YES | |
| # If the treeview is enabled (see GENERATE_TREEVIEW) then this tag can be | |
| # used to set the initial width (in pixels) of the frame in which the tree | |
| @@ -890,7 +890,7 @@ | |
| # If the GENERATE_LATEX tag is set to YES (the default) Doxygen will | |
| # generate Latex output. | |
| -GENERATE_LATEX = YES | |
| +GENERATE_LATEX = NO | |
| # The LATEX_OUTPUT tag is used to specify where the LaTeX docs will be put. | |
| # If a relative path is entered the value of OUTPUT_DIRECTORY will be |
結果
- Doxygen の PHP 対応は今もやはりイマイチ
- メモリ不足で API DOC を生成できないリポジトリがなくなった
- API DOC 生成のスピードは10倍以上に跳ね上がった
- API DOC 生成に使っているサーバの仕事を増やせる
- Windows 版もあるので、気軽に何回もドキュメント生成を試すことができる
- ドキュメントの品質向上に繋がるかも
いちばん上の階層のドットファイルは rm -r * では削除されない。 ↩