PEAR HTTP_Client::post()でファイル送信

ここには
integer HTTP_Client::post (
　string $url,
　mixed $data [, boolean $preEncoded = FALSE [, array $files = array()]]
)
とあって、
■string $url
URL を指定します。
■mixed $data
送出するデータを指定します。
■boolean $preEncoded
データがすでに urlencode されているかどうかを指定します。
■array $files
アップロードするファイルを指定します。配列の要素は、 以下の形態であるべきです:array(name, filename(s)[, content type])。 HTTP_Request::addFile() を参照してください。

などと説明がある。実はこれは嘘。
HTTP/Client.phpのソースを当たると

...
foreach ($files as $fileData) {
　　$res = call_user_func_array(array(&$request, 'addFile'), $fileData);
...

という記述がある。つまり
　$files = array('file1', '/home/user1/fileA.txt');
では駄目で、
　$files = array(array('file1', '/home/user1/fileA.txt'));
としておかないと意図したようには動かない。

ただ、この実装のおかげで
「一度のPOSTで複数のファイルが送れる」
という恩恵もある。
解説がちゃんとしてないだけで、こっちの方が便利ではある。

…ところがソース中のmethod post()のコメントにも
　 * @param　　array　Files to upload. Elements of the array should have the form:
　 *　　　　　　array(name, filename(s)[, content type]), see HTTP_Request::addFile()
とか平気で書いてあるから困ったもんだ。


※なお、この文章は「HTTP_Client Ver 1.1.1」に基づいております。