मैं पर्ल कोड में दस्तावेजों को संक्षेप में कैसे कर सकता हूं?

Question

मैं दस्तावेज के कोड के बगल में पीओडी टिप्पणियों के साथ एक तरह की शाब्दिक प्रोग्रामिंग शैली का पक्ष लेता हूं।

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 
    ... 
} 

और यह पूर्ण पॉड को विस्तारित किए जाते हैं:

=head1 NAME 

Foo - Foobar helper module for Foos 

=head1 METHODS 

=head2 foo ($bar, $doz) 

Lorem ipsum hopladi and hoplada. 

मुझे लगता है कि यह एक पॉड के साथ संभवतः होना चाहिए वहाँ एक रास्ता इस तरह किसी भी दोहराई जाने वाली और अनावश्यक वाक्य रचना के बिना अधिक संक्षिप्त लिखने के लिए नहीं है :: वीवर प्लगइन लेकिन पॉड :: वीवर के आर्किटेक्चर को समझने की कोशिश कर रहा है :: जिला और पीपीआई ने संयुक्त मस्तिष्क को चोट पहुंचाई :-(

Answer 1

मैंने दो अलग-अलग कार्यान्वयन (पर्ल परियोजनाओं के लिए) Natural Docs और OODoc का उपयोग किया है आपके आर के करीब equirement। मैं उनमें से किसी की भी सिफारिश नहीं करता, क्योंकि मुझे भाषा के बावजूद स्वत: उत्पन्न दस्तावेज पसंद नहीं है। अच्छे दस्तावेज के लिए समय और प्रयास की आवश्यकता होती है, अन्यथा आप दस्तावेज के कंकाल के साथ समाप्त होते हैं जो बेकार है।

Answer 2

मैं पूछकर शुरू करूंगा कि आपको इतना संक्षिप्त दस्तावेज़ीकरण बयान क्यों चाहिए?

मैंने प्राकृतिक डॉक्स का उपयोग किया है, और मुझे यह वाकई पसंद है। दस्तावेज़ीकरण की मेरी शैली संक्षिप्त नहीं है लेकिन मुझे इसे पठनीय लगता है। उदाहरण:

=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 

प्राकृतिक दस्तावेज़ अपने आप समारोह या विधि नाम लेने के लिए सक्षम है। इसके अलावा मैं इसे अपने जावास्क्रिप्ट स्रोतों और वैश्विक दस्तावेज दस्तावेज करने के लिए उपयोग करता हूं, और उनके बीच क्रॉस-लिंक डाल सकता हूं।