Нет ли лучшего способа документировать код Perl, чем POD?

Ответ 1

Быстрый поиск Doxygen Filter, который позволяет вам использовать Doxygen (которые очень близки к Javadoc) для документирования кода Perl.

Ответ 2

Хорошо, POD является общепринятым стандартом для публикации документации Perl.

Я нахожу это довольно раздражающим для поддержания; Недавно я экспериментировал с использованием Pod::Weaver для поддержки документации и сборки ее в Pod на выпуск. Это немного сложно в том, что он довольно гибкий в том, как вы фильтруете и создаете POD, и можете делать с немного дополнительной документацией (в POD или иначе). Но кажется многообещающим. Еще слишком рано для меня, чтобы дать больше суждения, чем это, но это кажется многообещающим.

Надеюсь, что это поможет

Ответ 3

Почему, по-вашему, код трудно читать с помощью Pod? Является ли код трудным для чтения с другим кодом вокруг него? Возможно, вы вкладываете слишком много в определенную часть кода, вместо того, чтобы писать небольшие методы и т.д. Вы уверены, что это не ваш код, который трудно читать?

Вам не нужно размещать всю вашу документацию в конце кода. Pod отлично сочетается с кодом, позволяя вам разместить документацию для подпрограммы или метода рядом с подпрограммой или методом.

Есть ли еще одна проблема с Pod?

Ответ 4

Единственный раз, когда у меня была проблема с POD, используется текстовый редактор, t выделите его правильно.

Так же, как все в Java this кажется слишком многословным:

/**
 * Returns an Image object that can then be painted on the screen. 
 * The url argument must specify an absolute  

{@link URL}. The name
 * argument is a specifier that is relative to the url argument. 
 * <p>
 * This method always returns immediately, whether or not the 
 * image exists. When this applet attempts to draw the image on
 * the screen, the data will be loaded. The graphics primitives 
 * that draw the image will incrementally paint on the screen. 
 *
 *  

@param  url  an absolute URL giving the base location of the image
 *  

@param  name the location of the image, relative to the url argument
 *  

@return      the image at the specified URL
 *  

@see         Image
 */
 public Image getImage(URL url, String name) {
        try {
            return getImage(new URL(url, name));
        } catch (MalformedURLException e) {
            return null;
        }
 }

По сравнению с эквивалентным Perl.

=item getImage( url, name )

This method always returns immediately, whether or not the 
image exists. When this applet attempts to draw the image on
the screen, the data will be loaded. The graphics primitives 
that draw the image will incrementally paint on the screen. 

url must be an absolute URL giving the base location of the image

name is the location of the image, relative to the url argument

=cut

sub getImage{
  my ($url,$name) = @_;

  ...
}

Ответ 5

Возможно, вам стоит взглянуть на Rinci. Примеры приложений, которые используют это: Файл:: RsyBak, Git:: Bunch, Приложение:: OrgUtils.

Здесь вы документируете модули. Вы объявляете% SPEC в своем модуле и размещаете внутри него документацию. Каждая функция получает свой ключ. Существуют предопределенные поля. Локализация поддерживается. Форматирование выполняется в Markdown. Пример:

$SPEC{':package'} = {
    summary => 'Module to do foo',
    "summary.alt.lang.id_ID" => "Modul untuk melakukan foo",
    description => <<EOT,
Blah...
...
EOT
    links => [...],
};
$SPEC{func1} = {
    summary => '...',
    description => '...',
    args => {
        arg1 => {
            schema => ...,
            summary => ....,
            description => ...,
        },
    },
    examples => [...],
    links => [...],
    ...
};

Вместо того, чтобы использовать стиль Java или Perl 5 для размещения документации в "комментариях", он использует структуру данных, непосредственно доступную для программ. (Обратите внимание, что Perl 6 также идет по этому пути.) Подумайте об этом, поскольку Python docstring сошел с ума (или структурировал).

Существуют инструменты для генерации POD, текста, HTML из метаданных (spec). Помимо документации, метаданные также полезны для других вещей, таких как проверка аргументов, интерфейс командной строки и т.д.

Раскрытие информации: Я разработчик.

Ответ 6

Сам я часто нахожу желающим воспроизвести записи кода в документации. Тем не менее, чтобы узнать, как я могу обмануть POD, чтобы прочитать код при подкачке, позволяя выполнить код во время разбора. Действительно ли я должен согласиться на это:

=head1 Variables

use vars (%V &C)

=cut

use vars (%V %C)

=head2 Constants

$C{hashConstant1} = "/path/to/file"

=cut

$C{hashConstant1} = "/path/to/file";

=head2 Variables

$V{strVar1} = undef

=cut

$V{strVar1} = undef;

Затем снова для большинства языков требуется двойная печать для документа.