Как я могу кратко документировать методы в коде Perl?

Я предпочитаю буквальный стиль программирования с комментариями POD рядом с кодом, который они документируют. К сожалению, это раздувает код, который не очень Perlish ;-) Лучший способ, который я смог найти, это использовать Dist::Zilla с Pod::Weaver как это:

package Foo;
#ABSTRACT: Foobar helper module for Foos

=method foo ( $bar, $doz )

Lorem ipsum hopladi and hoplada.

=cut

sub foo {
   ...
}

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

package Foo;
#ABSTRACT: Foobar helper module for Foos

#METHOD: Lorem ipsum hopladi and hoplada.
sub foo { # $bar, $doz
   ...
}

И разверните это до полного POD:

=head1 NAME 

Foo - Foobar helper module for Foos

=head1 METHODS

=head2 foo ( $bar, $doz )

Lorem ipsum hopladi and hoplada.

Я думаю, что это должно быть, возможно, с плагином Pod:: Weaver, но попытка понять архитектуру Pod:: Weaver в сочетании с Dist:: Zilla и PPI причинила мне боль :-(


perl dist-zilla perldoc perl-pod
person Jakob    schedule 28.08.2012    source источник

Ответы (2)


arrow_upward
2
arrow_downward

Я использовал две разные реализации (для проектов Perl) Natural Docs и OODoc, которые близки к вашим требованиям. Я не рекомендую ни один из них, просто потому, что мне не нравится автоматически генерируемая документация независимо от языка. Хорошая документация требует времени и усилий, иначе вы получите бесполезный скелет документации.

person chansen    schedule 28.08.2012
comment
Спасибо. Я бы различал документацию в виде пояснений и примеров (которые обычно находятся в разделе DESCRIPTION и SYNOPSIS в Perl) и документацию по назначению метода и синтаксису вызова. Первое необходимо для хорошей документации, второе просто удобно и может быть автоматически сгенерировано очень хорошо. - person Jakob; 29.08.2012

arrow_upward
1
arrow_downward

Я начну с вопроса, зачем вам нужны такие краткие формулировки документации?

Я использовал Natural Docs, и мне это очень нравится. Мой стиль документации не лаконичен, но я нахожу ее читабельной. Пример:

=begin nd

Check if a document name is available.

A name is available iff the name is not used by any other document related to the same study
excepted if it is another version of the same document.

Params:
    name        - Proposed document name to be checked : Str.
    study       - the study related to the document
    parent      -  parent document or undef if none : <Document>
    current_instance - the curretn document instance in case of an update


Returns:
    true iff the proposed name is valid

Exception:
    Dies on bad args or errors.

=cut

Natural Docs может автоматически выбирать имя функции или метода. Кроме того, я использую его для документирования своих исходников javascript и глобальной документации и могу вставлять перекрестные ссылки между ними.

person Karl Forner    schedule 03.09.2012
comment
Если я подробно документирую метод, краткость не имеет значения, но в некоторых случаях достаточно одного предложения и списка параметров. Я прошу только для этого случая. - person Jakob; 03.09.2012