Rust: दस्तावेज़-टिप्पणी शैली मार्गदर्शिका विकसित करें

को निर्मित 5 जन॰ 2013 · 17टिप्पणियाँ · स्रोत: rust-lang/rust

1.0 रिलीज से पहले बहुत सारे पुस्तकालय कोड बदलने की उम्मीद के साथ, अब ऐसा करने का कोई मतलब नहीं है, लेकिन कोर और एसटीडी पुस्तकालयों को एपीआई प्रलेखन के लिए एक सुसंगत शैली का उपयोग करना चाहिए। विकी सम्मेलनों को निर्दिष्ट करने के लिए कुछ प्रयास करता है, लेकिन इन्हें बाहर निकालने और वास्तव में कोडबेस पर लागू करने की आवश्यकता है।

अभी, कुछ डॉक्टर-टिप्पणियाँ थर्ड-पर्सन सांकेतिक में लिखी गई हैं:

pub fn map<T, U>(opt: &Option<T>, f: fn(x: &T) -> U) -> Option<U> {
    //! Maps a `some` value by reference from one type to another

और कुछ अनिवार्य में लिखे गए हैं:

pub fn chain<T, U>(opt: Option<T>,
                   f: fn(t: T) -> Option<U>) -> Option<U> {
    /*!
     * Update an optional value by optionally running its content through a
     * function that returns an option.
     */

ये दो उदाहरण एक और विसंगति को दर्शाते हैं: कुछ सारांश (टिप्पणी की पहली पंक्ति) में कोई अंतिम विराम चिह्न नहीं है, जबकि अन्य एक अवधि के साथ समाप्त होते हैं।

एक और चीज जो भिन्न होती है वह है टिप्पणी शैली। कुछ डॉक्टर-टिप्पणियां इस तरह दिखती हैं

/*!
 * foo...
 * bar...
 * baz...
 */

जबकि अन्य दिखते हैं

/*!
 foo...
 bar...
 baz...
 */

एक बार जब ये नियम (और अन्य) संहिताबद्ध हो जाते हैं, तो मुझे डॉक्टर-टिप्पणियों के माध्यम से जाना और उन्हें अपडेट करना शुरू करने में खुशी होगी।

P-low

स्रोत

ghost

सबसे उपयोगी टिप्पणी

वर्णनात्मक शैली:

सी# : Sorts the elements ... http://msdn.microsoft.com/en-gb/library/w56d4y5z%28v=vs.85%29.aspx#United %20Kingdom%20%28English%29
सी++ : ... sorts the elements ... http://www.sgi.com/tech/stl/sort.html
जाओ : ... sorts data ... http://golang.org/pkg/sort/#Sort
हास्केल एल: ... takes an element and a list and inserts the element into the list ... http://hackage.haskell.org/package/base-4.6.0.1/docs/Data-List.html
जावा : Sorts the specified array ... http://docs.oracle.com/javase/7/docs/api/java/util/Arrays.html
रूबी : Sorts self in place. http://www.ruby-doc.org/core-2.1.0/Array.html#method -i-sort-21

अनिवार्य शैली:

ओकैम एल: ... sort a list ... http://caml.inria.fr/pub/docs/manual-ocaml/libref/List.html
पायथन : Sort the items ... http://docs.python.org/2/tutorial/datastructures.html

kud1ing 28 जन॰ 2014

👍2

सभी 17 टिप्पणियाँ

:+1: इस पर चर्चा करने के लिए। मैं डॉक्स का योगदान करना चाहता हूं, लेकिन इसके पूरा होने के बाद मैं आपके लिए और अधिक काम नहीं करना चाहता। ;)

steveklabnik 5 जन॰ 2013

तुलना के लिए, मानक पायथन शैली अनिवार्य "रिटर्न द ..." का उपयोग करना है, जो मुझे अच्छी तरह से काम करता है:

http://www.python.org/dev/peps/pep-0257/#one -line-docstrings

sophiebits 6 जन॰ 2013

गो गैर-अनिवार्य शैली पर बस गया है: http://golang.org/pkg/

kud1ing 6 जन॰ 2013

ट्राइएज के लिए विजिटिंग।

व्यक्तिगत रूप से, मैं अनिवार्य क्रियाओं और अंत में एक अवधि पसंद करता हूं। डॉक्टर टिप्पणी शैली के लिए, मुझे नहीं लगता कि हमें किसी विशेष तरीके को दूसरे पर लागू करना चाहिए, कम से कम नहीं, जबकि भाषा इसे करने के कई तरीकों को परिभाषित करती है। साथ ही, मेरा पसंदीदा तरीका है

/**
 * doc string
 */

bblum 3 जुल॰ 2013

मैं अनिवार्यता को भी पसंद करता हूं। शैली को प्रकारों और तर्कों को संदर्भित करने के लिए एक एकीकृत वाक्यविन्यास भी शामिल करने की आवश्यकता है, इसलिए rustdoc उन्हें ठीक से एनोटेट/हाइपरलिंक कर सकता है। हालांकि यह सड़क के नीचे है

emberian 7 जुल॰ 2013

ट्राइएज के लिए विजिटिंग। इस बारे में मेरी बहुत कम राय है।

msullivan 23 अग॰ 2013

वर्णनात्मक शैली:

सी# : Sorts the elements ... http://msdn.microsoft.com/en-gb/library/w56d4y5z%28v=vs.85%29.aspx#United %20Kingdom%20%28English%29
सी++ : ... sorts the elements ... http://www.sgi.com/tech/stl/sort.html
जाओ : ... sorts data ... http://golang.org/pkg/sort/#Sort
हास्केल एल: ... takes an element and a list and inserts the element into the list ... http://hackage.haskell.org/package/base-4.6.0.1/docs/Data-List.html
जावा : Sorts the specified array ... http://docs.oracle.com/javase/7/docs/api/java/util/Arrays.html
रूबी : Sorts self in place. http://www.ruby-doc.org/core-2.1.0/Array.html#method -i-sort-21

अनिवार्य शैली:

ओकैम एल: ... sort a list ... http://caml.inria.fr/pub/docs/manual-ocaml/libref/List.html
पायथन : Sort the items ... http://docs.python.org/2/tutorial/datastructures.html

kud1ing 28 जन॰ 2014

👍2

मैं वर्णनात्मक संस्करणों को स्वयं पसंद करता हूं क्योंकि एक विधि परिभाषा तब तक कुछ नहीं करती जब तक कि मैं इसे नहीं बताता:

class Machine
{
    // Self-destructs the machine, if necessary.
    void self_destruct();
};

// Self-destruct!
if ( emergency )
  machine.self_destruct();

kud1ing 28 जन॰ 2014

मैं kud1ing के तर्क के प्रति समझदार हूं। इसके अलावा, यदि आप एक पंक्ति को जोर से पढ़ते हैं जिस तरह से इसे दस्तावेज़ में प्रस्तुत किया गया है:

शून्य योगात्मक पहचान देता है, 0.

तब घोषणात्मक रूप इसे एक वास्तविक वाक्य बनाता है "zero" returns the additive identity, 0. ।

Armavica 28 जन॰ 2014

@Armavica : जो वास्तव में The method "zero" returns the additive identity, 0 का संक्षिप्त रूप है।

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

kud1ing 28 जन॰ 2014

दस्तावेज़ीकरण में उदाहरणों की शैली के बारे में https://github.com/mozilla/rust/issues/9403 भी है।

huonw 29 जन॰ 2014

हल।

pnkfelix 6 फ़र॰ 2014

सीसी https://github.com/mozilla/rust/issues/12928

brson 16 मार्च 2014

यहां टिप्पणियों से, वर्णनात्मक शैली (उदाहरण के लिए, "एक बाइट को एक स्ट्रिंग में कनवर्ट करता है।") अनिवार्य शैली ("एक बाइट को एक स्ट्रिंग में कनवर्ट करें") से अधिक लोकप्रिय लगता है। मुझे इस बात की ज्यादा परवाह नहीं है कि हम किस रास्ते पर जाते हैं, लेकिन इस पर आधिकारिक निर्णय लेना अच्छा होगा।

lkuper 16 मार्च 2014

मुझे लगता है कि इसे अनिवार्य शैली कहना गलत है। यह अनिवार्य नहीं है, क्योंकि यह किसी को कुछ भी करने का निर्देश नहीं दे रहा है। मुझे लगता है कि यह पहला व्यक्ति वर्तमान संकेतक है। मुझे संदेह है कि लिखने का आग्रह

/// Frob the twaddle.
fn frob() {}

"मैं कार्य कर रहा हूँ। मैं क्या करूँ?" की मानसिकता से उपजा है, इसलिए यह पहला व्यक्ति वर्तमान संकेतक है।

हालांकि, प्रलेखन पढ़ते समय, अधिकांश पाठक स्वाभाविक रूप से फ़ंक्शन को प्रथम-व्यक्ति विषय के बजाय तीसरे व्यक्ति के एकवचन विषय के रूप में मानेंगे। इसके लिए, प्रलेखन को पहले व्यक्ति के बजाय तीसरे व्यक्ति के एकवचन में लिखा जाना चाहिए।

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

लेकिन मैं इस तर्क को प्रेरक नहीं मानता। दस्तावेज़ीकरण के लिए प्राथमिक उपयोग-मामला पाठक को बता रहा है कि एपीआई को कैसे _use_ किया जाए, न कि इसे कैसे लागू किया जाए। एक एपीआई के उपयोग की संख्या कार्यान्वयन की संख्या (सभी मामलों में सबसे गूढ़ मामलों में) से काफी अधिक है। इसलिए, मेरा मानना है कि यह तीसरे व्यक्ति के एकवचन में वर्तमान संकेतक का उपयोग करने के लिए अधिक समझ में आता है, यहां तक कि विशेषता विधियों के लिए भी अनिवार्यता का उपयोग करने के लिए।

lilyball 1 जुल॰ 2014

👍1

इससे निपटने के लिए एक और बात: हाइपेंस या एन डैश:

https://en.wikipedia.org/wiki/Dash#Relationships_and_connections

इन समन्वय/संबंध/कनेक्शन प्रकार के शब्दों में हाइफ़न के बजाय एन डैश के लिए वरीयता शैली वरीयता का मामला है, न कि अंतर्निहित ऑर्थोग्राफ़िक "शुद्धता"; दोनों समान रूप से "सही" हैं, और कुछ शैली गाइडों में प्रत्येक पसंदीदा शैली है।

steveklabnik 5 अग॰ 2014

मैंने एक आरएफसी जमा किया है: https://github.com/rust-lang/rfcs/pull/505

steveklabnik 8 दिस॰ 2014

क्या यह पृष्ठ उपयोगी था?

0 / 5 - 0 रेटिंग्स

Rust: दस्तावेज़-टिप्पणी शैली मार्गदर्शिका विकसित करें

सबसे उपयोगी टिप्पणी

सभी 17 टिप्पणियाँ

संबंधित मुद्दों