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

Question

Я предпочитаю своего рода буквальный стиль программирования с комментариями 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 сделала мой мозг поврежденным:-(

Answer 1

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

Answer 2

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

Я использовал 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 и глобальной документации и могу вставлять перекрестные ссылки между ними.