मल्टीलाइन क्लोजर डॉकस्ट्रिंग

Question

मैंने देखा है कि क्लोजर मल्टीलाइन डॉकस्ट्रिंग को ज्यादातर मामलों में मैन्युअल रूप से स्वरूपित किया जाता है, जिसमें clojure.core में शामिल हैं। https://github.com/clojure/clojure/blob/master/src/clj/clojure/core.clj से उदाहरण:

(defn flatten 
    "Takes any nested combination of sequential things (lists, vectors, 
    etc.) and returns their contents as a single, flat sequence. 
    (flatten nil) returns an empty sequence." 
    {:added "1.2" 
    :static true} 
    [x] 
    (filter (complement sequential?) 
      (rest (tree-seq sequential? seq x)))) 

यह अजीब लगता है, के रूप में यह मतलब है कि अलग अलग docstrings लाइन चादर लंबाई आदि जो मैन्युअल रूप से बनाए रखा जा करने की जरूरत है होगा।

क्या मल्टीलाइन डॉकस्ट्रिंग को प्रारूपित करने का एक बेहतर तरीका है?

Answer 1

यदि आप Emacs का उपयोग कर रहे हैं, clojure-mode.eltechnomancy's Github से लें, जो ईएलपीए में से एक से अलग है (मुझे नहीं पता कि दोनों संस्करण 1.11.5 होने का दावा क्यों करते हैं, शायद कोई उस पर टिप्पणी कर सकता है?) लेकिन इसमें शामिल है clojure-fill-docstring जो अच्छे इंडेंटेशन और लाइनव्रैपिंग के साथ डॉकस्ट्रिंग को प्रारूपित करेगा, डिफ़ॉल्ट रूप से C-c M-q पर बाध्य होगा।

यह इस ले जाएगा:

(defn flatten 
    "Takes any nested combination of sequential things (lists, vectors, etc.) and returns their contents as a single, flat sequence. (flatten nil) returns an empty sequence." 
    {:added "1.2" 
    :static true} 
    [x] 
    (filter (complement sequential?) 
      (rest (tree-seq sequential? seq x)))) 

और यह इस में बदल जाते हैं:

(defn flatten 
    "Takes any nested combination of sequential things (lists, vectors, 
    etc.) and returns their contents as a single, flat sequence. 
    (flatten nil) returns an empty sequence." 
    {:added "1.2" 
    :static true} 
    [x] 
    (filter (complement sequential?) 
      (rest (tree-seq sequential? seq x)))) 

आप docstring अंदर अपनी बात के साथ C-c M-q कर के बाद।

Answer 2

क्या मल्टीलाइन डॉकस्ट्रिंग को प्रारूपित करने का एक बेहतर तरीका है?

मेरा सुझाव है कि आप अपने डॉकस्ट्रिंग में Markdown स्वरूपण का उपयोग करें। क्यों यहाँ कुछ कारण हैं:

• यह क्या README के ​​दशक में GitHub पर प्रयोग किया जाता है और इस परियोजना विकिज़ (और कई Clojure उन का उपयोग करें और GitHub से परिचित हैं) है।

• विभिन्न Clojure परियोजनाओं में numberof.md filesyoufind वर्तमान द्वारा पहचानने, यह Clojure उपयोगकर्ताओं के बीच एक पसंदीदा मार्कअप प्रारूप प्रतीत होता है।

• लोकप्रिय Marginalia डॉक उपकरण renders markdown प्रारूपित docstrings और टिप्पणियां (और मैं समझता हूँ कि Autodoc (उपकरण अंततः docstrings में markdown प्रस्तुत करना होगा और साथ ही clojure.org पर डॉक्स उत्पन्न करने के लिए प्रयोग किया जाता) है)।

• यह सादा पाठ के रूप में अच्छा लगता है, टाइप करना आसान है, किसी भी विशेष संपादक समर्थन की आवश्यकता नहीं है, और मार्कअप न्यूनतम और याद रखना आसान है।

इसके अलावा, आप शायद यह पहले से परिचित हैं, प्रश्न/उत्तर/टिप्पणी के लिए Stackoverflow uses it के बाद से (और reddit और विभिन्न ब्लॉग टिप्पणी प्रणाली जैसी साइटों Markdown का उपयोग के साथ-साथ)।

Answer 3

मैं @uvtc से सहमत हूं कि मार्कडाउन एक अच्छा विकल्प है। एक परिशिष्ट के रूप में, मैं यह ध्यान रखना चाहता हूं कि आरईपीएल में उपयोग के लिए अपना खुद का मार्कडाउन डॉक व्यूइंग फ़ंक्शन उत्पन्न करना तुच्छ है। निम्न कोड मानता है कि आपके क्लासपाथ पर मार्कडाउन-क्लोज पैकेज है (उदा।देव निर्भरता के माध्यम से), और OSX में एक आरईपीएल उपयोग कर रहे हैं:

(ns docs 
    (:require [clojure.java.shell :as s] 
      [markdown.core :as md])) 

(defmacro opendoc [name] 
    `(do 
     (md/md-to-html (java.io.StringReader. (:doc (meta (var ~name)))) "/tmp/doc.html") 
     (s/sh "open" "/tmp/doc.html") 
    ) 
) 

आप clojure.repl/doc विशेष मामलों को संभालने के लिए के लिए स्रोत को देखने के लिए चाहते हो सकता है (उदाहरण के लिए यह एक मान लिया गया है कि तुम एक में पारित हो जाएगा एक var के लिए उचित प्रतीक)। यह भी अच्छा हो सकता है कि फाइलनाम प्रत्येक अनुरोध के लिए उसी फ़ाइल नाम का पुन: उपयोग करने के बजाय "कैशिंग" के लिए नेमस्पेस/फ़ंक्शन नाम को प्रतिबिंबित कर सकता है ... लेकिन मैं इसे चित्रण उद्देश्यों के लिए सरल बना रहा हूं।

ओएसएक्स open कमांड बस ओएस को अपने प्रकार का पता लगाकर फ़ाइल खोलने के लिए कहता है। इस प्रकार:

REPL=> (docs/opendoc my.ns/f) 

आपके डिफ़ॉल्ट ब्राउज़र को आपके फ़ंक्शन के डॉकस्ट्रिंग के HTMLified संस्करण को खोलने का कारण बन जाएगा।

एक अन्य चेतावनी: यदि आप अपने बहु स्ट्रिंग (जो संपादकों आमतौर पर करते हैं) इंडेंट हैं, तो आपके एमडी अप weirdness के साथ खत्म हो सकता है (उदाहरण के लिए बुलेट सूचियों हो सकता है एक तरह से आप का इरादा नहीं रखते घोंसला)। इसे हल करने का एक तरीका यह है कि उसे वापस ट्रिम करना है।

(defn boo 
    " 
    # Title 
    My thing 

    * Item one 
    * Item two 
    " 
    [args] ...) 

और फिर opendoc समारोह को संशोधित पहले एक छोड़ दिया ट्रिम लागू करने के लिए: प्रारूप करने के लिए अपने संपादक

(defn ltrim [str] (clojure.string/replace str #"(?m)^ {0,3}" "")) 

(defmacro opendoc [name] 
    `(do 
    (md/md-to-html (java.io.StringReader. (ltrim (:doc (meta (var ~name))))) "/tmp/doc.html") 
    (s/sh "open" "/tmp/doc.html") 
    ) 
)