Best practice для оформления документации

[Oleg Alistratov]

On 09.09.2011 17:12, Serg V. Gulko wrote:

> Коллеги, хотелось бы узнать, как Вы оформляете документацию к своему
> коду на Perl.
> Есть ли какие-нибудь более-менее общепринятые рекомендации по оформлению
> методов классов.

Пробовал NaturalDocs. Не слишком впечатлил.

Пробовал Doxygen, он покрасивей, но perl без плясок с бубном не умеет.

POD толком никто из них воспринять все равно не может.

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

 > Мне бы хотелось указывать входные аргументы, выходные параметры и
 > исключения, если метод их порождает.

Что мне больше всего нравится в perl6 (кроме грамматик), так это 
развесистые прототипы функций. Интерфейсы даже.

А пока perl6 не на конвейере, приходится как-то самому придумывать
какую-то формализацию описаний в дополнение к обычному PODу;
затем POD::Parser в руки и вперед.



--
Олег