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

Question

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

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

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

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

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

Answer 1

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

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

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

Answer 2

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

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

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

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