어떻게 Perl 코드에서 메서드를 간결하게 문서화 할 수 있습니까?

Question

필자는 POD 주석이 문서화 된 코드 옆에있는 일종의 리터럴 프로그래밍 스타일을 선호합니다.

package Foo; 
#ABSTRACT: Foobar helper module for Foos 

=method foo ($bar, $doz) 

Lorem ipsum hopladi and hoplada. 

=cut 

sub foo { 
    ... 
} 

한 빈 줄을 제거하는 주장 할 수 있지만,이 또한 가독성을 감소 : 불행하게도이 매우 Perlish하지 않은 코드가 bloats ;-) 내가 지금 찾을 수있는 가장 좋은 방법은 그런 Pod::Weaver와 Dist::Zilla을 사용하는 것입니다 .

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. 

이 같은 모든 반복하고 불필요한 구문없이 더 간결하게 쓸 수있는 방법이 없을까 :: Weaver Plugin은 Dist : Zilla와 PPI의 아키텍처를 이해하려고 노력하면서 내 머리가 아프다 :-(

Answer 1

두 개의 서로 다른 구현 (Perl 프로젝트 용) Natural Docs 및 OODoc을 사용했습니다. 너의 가까이에 equirement. 언어에 관계없이 자동 생성 된 설명서가 마음에 들지 않기 때문에 그 중 어떤 것도 권장하지 않습니다. 좋은 문서는 시간과 노력이 필요합니다. 그렇지 않으면 쓸모없는 문서의 골격으로 끝납니다.

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 

자연 문서가 자동으로 함수 또는 메소드 이름을 선택 할 수 있습니다. 또한 자바 스크립트 소스 및 글로벌 문서를 문서화하는 데 사용하고 이들 사이에 상호 링크를 삽입 할 수 있습니다.