PHPには__halt_compiler()なんて言う関数があったんですね。
マニュアルでは埋め込んだインストールデータを読み込むのに使っていますが、
設定保存に使う例もあり、考え方次第で使えそうだと思いました。

と言うことで、ライブラリが直接実行された場合はプログラムとして実行する
の応用で、ライブラリーが直接実行した場合はドキュメントも表示する、と言うのを試してみました。

ライブラリーを直接実行した場合
そのライブラリーをrequireした場合

ライブラリーのソース
requireする例のソース

ライブラリーのソースを見てもらうとすぐわかるのですが、
__halt_compiler();呼び出しの後に、このファイルのドキュメントを普通のhtml形式で書いています。
そうすると、通常は表示されないので、直接実行した場合のみfopenして表示する処理を入れています。

perlでも__END__がプログラムの終わりを表すことを利用して、ライブラリーの中にperlpodと呼ばれる形式で
ドキュメントを含めるのが一般的のようですが、PHPでもドキュメントを含んだライブラリーを増やして行くのはいかがでしょうか。

perlpodが組み込んであるライブラリーの例
pod形式概要
__END__の説明
perlpodマニュアル

CLIで実行された場合にはhtmlではなくてプレインテキストで出力できるようにしたり
perlのように外部プログラムに加工させたり、色々応用することもできそうです。

(お気に召した方はhtmlとして表示するとドキュメントとサンプルが動くjsファイルもどうぞ)