TSfree 発言

  書式が分からないのでちょっと動かして気づいた点を列挙しておきます。
  （その1、その2 と階層が合わなくなってしまった。。。）

日本語の扱い
============

  この手のツールでいちばんよくある問題は生成される HTML に non-us-ascii 
をまったく考慮しない charset が指定されているケースなのですが、Pdoc はそ
ういうことはありませんでした。euc のコードに対して Pdoc を掛けたら、通常
は文字化けなどの問題は出ないと思います。文字コード判別の決め手にならない
文字だけでコメントが書いてあったら分かりませんが。

documentation されるもの
========================

ぱっと見で。

package
-------

- package 変数
 - これには無名ハッシュリファレンスは含まれないのでがっつり OO で書いて
   いると面白くない感じ。
- include methods
 - require が列挙される
- ISA
- たぶん =head description（大文字小文字の区別とかあんのかな？）
- たぶん =head synopsis（大文字小文字の区別とかあんのかな？）

method
------

  | で始まる行が実際の記述です。なかなかプレーンテキストで表現するのって
難しい。

++ 書き方1 ++

| =head1 method名
|   ここに説明

  てな記述の場合は method のリストアップ、「ここに説明」の部分を 
description への反映を行ってくれる。

++ 書き方2 ++

|=head1 method( 引数 )

  の書き方はそのまま引数を含めて method がリストアップされた。

++ 書き方3 ++

|=head1 NAME method名
|  ここに説明

  としたら No description になってしまった。

++ 書き方4 ++

|=head1 NAME mthod名
|=head2 DESCRIPTION
|  ここに説明

  もやっぱり No description

++ 書き方5 ++

|=head1 NAME
| method( 引数 )
| =head2 DESCRIPTION
| ごにょごにょ
| =head2 USAGE
| method( パス )

（ほんとは1行空きで）やっぱり No description


  うーん、NAME とか DESCRIPTION とか書いてあった方が perldoc コマンドで
の出力は見やすくなるのですが、そういう書き方をすると Pdoc に掛ける場合は
うまくないようです。

  とりあえず、=head から NAME だの DESCRIPTION だの特別な単語を置かずに
だらだら書くのが正しいようです。引数とか戻り値とかも別な head を立てずに
だらだら書いておけばそのまま description としてリストアップされる模様。

--
    ねこ丸