今アイデアマンズのWEB開発ではPHPをメイン言語としていますが、PHPDocumentorかdoxygenでリファレンスを生成してます。また、doxygenに手を入れて独自のフレームワーク「IDENIUM(アイデニウム)」のリファレンスを生成するものも作ってみましたが(宮永が)、実際のところどれも利用頻度は少なめ。
ソースコードとドキュメントの同期って、かなり大事ですけど未だ満足して使えるツールがない感じです。

これはすごい! WebでEclipseばりのコードブラウジング"Sorcerer"(MyCOMジャーナル)
確かに凄い。
PHPでも使えないかな。
将来的にはオープンソースの有名プロジェクトなんかでソースをHTMLに落としておいて、コードの間にその部分のアルゴリズムを説明するポンチ絵なんかをペタペタ貼り付けたりして、しかもソースは常に最新の状態に保たれていたりすると素敵。コードリーディングも楽しくなりますよね。