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

Question

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

Когда я использую комментарии POD в коде, код трудно читать. Когда я использую комментарии POD в конце файла, существует опасность, что документация не синхронизируется с кодом.

Мне не хватает стиля документации, похожего на Java.

/**
 * @description
 * ...
 */

Я ищу более простой и понятный стиль документации. Что-то подобное существует?

Answer 1

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

Answer 2

Ну, POD - это принятый стандарт для публикации документации по Perl.

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

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

Answer 3

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

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

Есть ли у вас еще какие-то проблемы с Pod?

Answer 4

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

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

/**
 * 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) = @_;

  ...
}

Answer 5

Возможно, вы захотите взглянуть на Ринчи. Примеры приложений, которые используют это: File:: RsyBak, Git:: Bunch, App:: 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.

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

Раскрытие: я разработчик.

Answer 6

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

=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;

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