क्लोजर प्रलेखन उपकरण के लिए कला का राज्य

Question

पिछले वर्ष या तो मैंने क्लोजर चर्चा सूची और क्लोजर कोड को दस्तावेज करने के लिए टूल के बारे में अन्य स्थानों पर विभिन्न घोषणाएं देखी हैं। ये मार्जिनिया जैसे पूर्ण-साक्षर प्रोग्रामिंग सिस्टम से हैं, और टूल को "छोटे टुकड़े में क्लोजर" (या यहां तक ​​कि इमाक्स ऑर्ग-मोड) "बनाने के लिए इस्तेमाल किया जा रहा है, जो ऑटोडोक और जावाडोक जैसे अधिक पारंपरिक जावाडोक-स्टाइल समाधानों के लिए है। कथित तौर पर क्लोजर के साथ इस्तेमाल किया जा सकता है। एक Google खोज कई अन्य लोगों को बदल देती है, शायद कुछ जो अधिक ध्यान देने योग्य हैं, और निश्चित रूप से कुछ जो दस्तावेज़ बनाने के लिए केवल व्यक्तिगत उपयोगिताएं हैं। मेरा सवाल यह है कि सबसे अच्छा प्रलेखन उपकरण क्या हैं, और उनके अनुभवों के आधार पर उनकी तुलनात्मक ताकत और कमजोरियां क्या हैं? मैंने आज तक किसी भी दस्तावेज़ीकरण उपकरण का उपयोग नहीं किया है, और एक या अधिक के साथ प्रयोग करने में दिलचस्पी है।

Answer 1

यदि आप एक साक्षर प्रोग्रामिंग दृष्टिकोण की तरह कुछ लेना चाहते हैं तो मुझे वास्तव में Marginalia पसंद है। मार्जिनिया आपके स्रोत कोड को पार करता है, और एक HTML स्वरूपित संस्करण बनाता है जिसमें कोड के बगल में टिप्पणियों के साथ एक बहुत ही स्पष्ट पाठ में सेट किया जाता है। टिप्पणियों को एक बहुत ही पठनीय अंतिम दस्तावेज़ के लिए प्रारूपित प्रारूपित किया जा सकता है। कुछ समय पहले मैंने जो स्रोत कोड लिखा है, उसकी समीक्षा करते समय, मुझे लगता है कि मार्जिनिया वास्तव में मदद करता है। Here's an example made from the Marginalia source itself।

ध्यान दें कि यह मूल साक्षर प्रोग्रामिंग वर्कफ़्लो से अलग है, जहां आप एक फ़ाइल लिखेंगे और उस से स्रोत कोड उत्पन्न होगा। मार्जिनिया के साथ, आप एक नियमित स्रोत कोड फ़ाइल लिखते हैं, और यह उस दस्तावेज़ीकरण से बाहर निकाला जाता है। आउटपुट साक्षर प्रोग्रामिंग से अपेक्षा की जा सकती है, लेकिन इस तरह से आप किसी भी विशेष साक्षर प्रोग्रामिंग समर्थन के बिना, एक संपादक में सिंटैक्स हाइलाइटिंग की उम्मीद कर सकते हैं।

यह लीनिंगेन के साथ इंटरऑपरेट करता है, और मुझे केक पर विश्वास है, हालांकि मैंने खुद को यह कोशिश नहीं की है।

Answer 2

Autodoc एक आसान जगह शुरू करने के लिए है और क्या Clojure core और Clojure contrib उपज है।

Maven के साथ उपयोग करने में आसान। मुझे यकीन नहीं है कि लीनिंगेन या केक के लिए प्लगइन्स मौजूद हैं या नहीं।

Answer 3

यदि आप पूरी तरह से साक्षर जाना चाहते हैं तो आपको org-babel-clojure एक नज़र देना चाहिए। org-bable emacs org-mode के लिए एक साक्षर प्रोग्रामिंग एक्सटेंशन है।

आप निम्नलिखित nrepl उपयोग करना चाहते हैं अपने .emacs में जोड़ा जाना चाहिए:

(defun org-babel-execute:clojure (body params) 
    "Execute a block of Clojure code with Babel." 
    (let ((result-plist (nrepl-send-string-sync (org-babel-expand-body:clojure body params) nrepl-buffer-ns)) 
     (result-type (cdr (assoc :result-type params)))) 
    (org-babel-script-escape 
    (cond ((eq result-type 'value) (plist-get result-plist :value)) 
      ((eq result-type 'output) (plist-get result-plist :value)) 
      (t      (message "Unknown :results type!")))))) 

Answer 4

Codox Clojure के लिए एक और अधिक हाल के प्रलेखन जनरेटर है।