marunomaruno-memo

marunomaruno-memo

PHP ソースからドキュメントを自動生成する (phpdocumentor)

2008年12月29日 | PHP
PHP ソースからドキュメントを自動生成する (phpdocumentor)
================================================================================

PHP ソースからドキュメントを自動生成させることができる。
ドキュメントの基になるのは、ドキュメントコメントといわれるもので、
/** で始まり、*/ で終わる形式のコメント。

また、その中に、次のようなタグをつけることで、ドキュメントに対して指示を出すこと
ができる。もちろん、これ以外にもいろいろとある。
---
* @author 作成者
* @version バージョン
* @param 引数名 意味
* @return 戻り値
---

PDT を使っていれば、このドキュメントコメントの基になるものはある程度自動生成する。
(Ctrl+Shift+J)


■インストール

pearコマンドを使ってインストールする。

---
>pear install --alldeps phpdocumentor
PHP Warning: Zend Debug Server for PHP 5.2.x cannot be found (expected at 'C:x
amppphpzendOptimizerlibDebuggerphp-5.2.xZendDebugger.dll') - try reinstalling the Zend Debug Server in Unknown online 0
downloading PhpDocumentor-1.4.2.tgz ...
Starting to download PhpDocumentor-1.4.2.tgz (2,421,028 bytes)
................................done: 2,421,028 bytes
downloading XML_Beautifier-1.2.0.tgz ...
Starting to download XML_Beautifier-1.2.0.tgz (12,948 bytes)
...done: 12,948 bytes
downloading XML_Parser-1.3.1.tgz ...
Starting to download XML_Parser-1.3.1.tgz (14,565 bytes)
...done: 14,565 bytes
downloading XML_Util-1.2.1.tgz ...
Starting to download XML_Util-1.2.1.tgz (17,729 bytes)
...done: 17,729 bytes
install ok: channel://pear.php.net/PhpDocumentor-1.4.2
install ok: channel://pear.php.net/XML_Parser-1.3.1
install ok: channel://pear.php.net/XML_Util-1.2.1
install ok: channel://pear.php.net/XML_Beautifier-1.2.0
---


■ドキュメント生成

phpdoc コマンドを使って生成する。

コマンド
---
phpdoc -t 生成ドキュメントのディレクトリー
-d ソースのディレクトリー
[-o HTMLのテンプレート]
---

現在の作業ディレクトリーの直下にソースを入れるディレクトリー(src)があり、また、
ドキュメントを doc ディレクトリーに入れたいときのコマンド

---
>phpdoc -t ./doc -d ./src
PHP Warning: Zend Debug Server for PHP 5.2.x cannot be found (expected at 'C:x
amppphpzendOptimizerlibDebuggerphp-5.2.xZendDebugger.dll') - try reinstall
ing the Zend Debug Server in Unknown online 0
PHP Version 5.2.6
phpDocumentor version 1.4.2

Parsing configuration file phpDocumentor.ini...
(found in C:xamppphpdata/PhpDocumentor/)...
: (略)
Total Documentation Time: 7 seconds
done
---


■ブラウザーでドキュメントを見る

上記のコマンドは、ドキュメントのテンプレートは指定してない。
見た感じは、JavaのAPIドキュメントもどきのようである。

見た目を変えるには、-o オプションを使い、ドキュメントのテンプレートを指定する。

□ドキュメントのテンプレート
---
HTML:frames:* - output is HTML with frames.
default - JavaDoc-like template, very plain, minimal formatting
earthli - BEAUTIFUL template written by Marco von Ballmoos
l0l33t - Stylish template
phpdoc.de - Similar to phpdoc.de's PHPDoc output
phphtmllib - Very nice user-contributed template
phpedit - Based on output from PHPEdit Help Generator

HTML:Smarty:* - output is HTML with no frames.
default - Bold template design using css to control layout
HandS - Layout is based on PHP, but more refined, with logo image
PHP - Layout is identical to the PHP website
---


■日本語ドキュメントを生成できるようにする

このままだと、日本語のドキュメントは文字化けする。
html ファイルのテンプレートで、日本語が使用できるような文字コード(utf-8など)を指定する。

これらのテンプレートは、上記のドキュメントのテンプレートごとにあるので、自分の使いたいテンプレートのものを変更する。（または、いっそのこと、すべて)

ここでは、デフォルトのテンプレートを使っているので、つぎのファイルをの文字コード部分を変更する。

C:xamppphpdataPhpDocumentorphpDocumentorConvertersHTMLframestemplatesd
efaulttemplatesheader.tpl
------------------------------------------------------


org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
  <html xmlns="http://www.w3.org/1999/xhtml">
        <head>
            
            <title>{$title}</title>
            <link rel="stylesheet" href="{$subdir}media/stylesheet.css" />
            <meta http-equiv='Content-Type' content='text/html; charset=utf-8

'/>
        </head>
        <body>
            {if $top3}
{/if}
------------------------------------------------------



■参考URL

phpDocumentorでドキュメントの自動生成
http://caspar.hazymoon.jp/php/phpDocumentor/

phpDocumentor: The complete documentation solution for PHP
http://phpdoc.org/index.php

Do You PHP? - phpDocumentor - PHPDocに代わるAPIドキュメント自動生成ツール
http://www.doyouphp.jp/tips/tips_phpdocumentor.shtml

PHPソースからドキュメントを生成するツール
http://www.1x1.jp/blog/2007/10/php_source_document.html


以上


最新の画像［もっと見る］

コメントを投稿