Нет ли лучшего способа документировать код 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 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) = @_; 

    ... 
} 

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 => [...], 
    ... 
}; 

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

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

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

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

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