Как заставить phpDocumentator понимать русский текст в исходниках на UTF-8:

1. нужно править файл Setup.inc.php. В нем есть метод createDocs, где нужно исправить следующее
- if (stristr($ret, "utf-8") !== "")
+ if (stristr($ret, "utf-8") === false)
{
$ret = utf8_decode($ret);
}


2. Пройтись глобальной заменой по всем (*.*) файлам документатора и заменить
charset=iso-8859-1'/>
на
charset=utf-8'/>

3. Необязательный (у меня и без этого заработало, но возможно это имеет значение при выводе мануала в XML)
Пройтись глобальной заменой по всем (*.*) файлам документатора и заменить
<?xml version="1.0" encoding="iso-8859-1"?>
на
<?xml version="1.0" encoding="utf-8"?>

P.S. Тестировалось на теме HTML:frames:default

Ну и на закуску, готовый плагин для Zend Studio for Eclipse

Это вещь достаточно распространенная и известная,
я всего лишь расскажу о ее синтаксисе и применении на практике.
Все будет приминительно ООП на PHP.
Сразу оговорюсь, формат применим к классам, их методам и свойствам,
и чтоб в итоге наших трудов мы получили не каляку-маляку из даблслешей,
а красиво написаную документацию, этот формат следует применять.