Best practice для оформления документации
Oleg Alistratov
ali at ali.org.ua
Fri Sep 9 08:37:14 PDT 2011
On 09.09.2011 17:12, Serg V. Gulko wrote:
> Коллеги, хотелось бы узнать, как Вы оформляете документацию к своему
> коду на Perl.
> Есть ли какие-нибудь более-менее общепринятые рекомендации по оформлению
> методов классов.
Пробовал NaturalDocs. Не слишком впечатлил.
Пробовал Doxygen, он покрасивей, но perl без плясок с бубном не умеет.
POD толком никто из них воспринять все равно не может.
Соответственно, выбрав конкретную систему документирования,
под нее комментарии и затачиваешь. Обычно у них есть какой-то птичий
язык, которым ты можешь уточнить смысл этого:
> Мне бы хотелось указывать входные аргументы, выходные параметры и
> исключения, если метод их порождает.
Что мне больше всего нравится в perl6 (кроме грамматик), так это
развесистые прототипы функций. Интерфейсы даже.
А пока perl6 не на конвейере, приходится как-то самому придумывать
какую-то формализацию описаний в дополнение к обычному PODу;
затем POD::Parser в руки и вперед.
--
Олег
More information about the Kiev-pm
mailing list