Tôi có thể viết các phương thức tài liệu ngắn gọn như thế nào trong mã Perl?

Question

Tôi ưu tiên một kiểu chương trình theo nghĩa đen với các nhận xét POD bên cạnh mã mà họ ghi lại. Thật không may này bloats mã, mà không phải là rất Perlish ;-) Cách tốt nhất tôi có thể tìm thấy bằng hiện nay là sử dụng Dist::Zilla với Pod::Weaver như thế:

package Foo; 
#ABSTRACT: Foobar helper module for Foos 

=method foo ($bar, $doz) 

Lorem ipsum hopladi and hoplada. 

=cut 

sub foo { 
    ... 
} 

Người ta có thể tranh luận để loại bỏ dòng trống nhưng điều này cũng làm giảm khả năng đọc . không có cách nào để viết ngắn gọn hơn mà không cần bất kỳ cú pháp lặp đi lặp lại và không cần thiết như thế này:

package Foo; 
#ABSTRACT: Foobar helper module for Foos 

#METHOD: Lorem ipsum hopladi and hoplada. 
sub foo { # $bar, $doz 
    ... 
} 

Và có được điều này mở rộng đến toàn POD:

=head1 NAME 

Foo - Foobar helper module for Foos 

=head1 METHODS 

=head2 foo ($bar, $doz) 

Lorem ipsum hopladi and hoplada. 

Tôi nghĩ rằng nó nên có thể với một Pod :: Plugin Weaver nhưng cố gắng hiểu kiến ​​trúc của Pod :: Weaver kết hợp với Dist :: Zilla và PPI khiến não tôi bị tổn thương :-(

Answer 1

Tôi đã sử dụng hai cách triển khai khác nhau (cho dự án Perl) Natural Docs và OODoc gần với r của bạn cổ phần. Tôi không đề nghị bất kỳ người nào trong số họ, đơn giản vì tôi không thích tài liệu tự phát không phân biệt ngôn ngữ. Tài liệu tốt đòi hỏi thời gian và nỗ lực, nếu không bạn kết thúc với một bộ tài liệu hướng dẫn là vô dụng.

Answer 2

Tôi sẽ bắt đầu bằng cách hỏi tại sao bạn cần báo cáo tài liệu ngắn gọn như vậy?

Tôi đã sử dụng Tài liệu tự nhiên và tôi thực sự thích nó. Kiểu tài liệu của tôi không súc tích nhưng tôi thấy nó có thể đọc được. Ví dụ:

=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 

Tài liệu tự nhiên có thể tự động chọn tên hàm hoặc phương thức. Hơn nữa, tôi sử dụng nó để ghi lại các nguồn javascript của tôi và tài liệu toàn cầu, và có thể chèn các liên kết chéo giữa chúng.