Rust
प्रलेखन

परिचय

वाक्य - विन्यास

• /// बाहरी प्रलेखन टिप्पणी (नीचे आइटम पर लागू होता है)

• //! इनर डॉक्यूमेंटेशन टिप्पणी (संलग्न वस्तु पर लागू होती है)

• कार्गो डॉक # इस पुस्तकालय टोकरे के लिए दस्तावेज तैयार करता है।

• कार्गो डॉक - ओपेन # इस लाइब्रेरी क्रेट और ओपन ब्राउज़र के लिए डॉक्यूमेंटेशन तैयार करता है।

• कार्गो डॉक-पी क्रेट # केवल निर्दिष्ट टोकरा के लिए प्रलेखन उत्पन्न करता है।

• कार्गो डॉक् -नो-डिप्स # इस लाइब्रेरी के लिए प्रलेखन बनाता है और कोई निर्भरता नहीं है।

• कार्गो परीक्षण # इकाई परीक्षण और प्रलेखन परीक्षण चलाता है।

टिप्पणियों

प्रलेखन लिट

यह सुनिश्चित करने के लिए कि सभी संभावित वस्तुओं को प्रलेखित किया गया है, आप संकलक से चेतावनी / त्रुटियां प्राप्त करने के लिए missing_docs लिंक का उपयोग कर सकते हैं। लाइब्रेरी-वाइड को चेतावनी प्राप्त करने के लिए, इस विशेषता को अपनी lib.rs फ़ाइल में रखें:

#![warn(missing_docs)]

आप इस लिंट के साथ लापता प्रलेखन के लिए त्रुटियां भी प्राप्त कर सकते हैं:

#![deny(missing_docs)]

डिफ़ॉल्ट रूप से, missing_docs की अनुमति है, लेकिन आप उन्हें इस विशेषता के साथ स्पष्ट रूप से अनुमति दे सकते हैं:

#![allow(missing_docs)]

यह एक मॉड्यूल के लिए लापता प्रलेखन की अनुमति देने के लिए एक मॉड्यूल में रखने के लिए उपयोगी हो सकता है, लेकिन अन्य सभी फाइलों में इसे अस्वीकार कर सकता है।

प्रलेखन टिप्पणियाँ

जंग दो प्रकार की प्रलेखन टिप्पणियाँ प्रदान करती है: आंतरिक प्रलेखन टिप्पणियाँ और बाहरी प्रलेखन टिप्पणियाँ। प्रत्येक के उदाहरण नीचे दिए गए हैं।

आंतरिक प्रलेखन टिप्पणियाँ

mod foo {
    //! Inner documentation comments go *inside* an item (e.g. a module or a 
    //! struct). They use the comment syntax //! and must go at the top of the
    //! enclosing item. 
    struct Bar {
        pub baz: i64
        //! This is invalid. Inner comments must go at the top of the struct,
        //! and must not be placed after fields.
    }
}

बाहरी प्रलेखन टिप्पणियाँ

/// Outer documentation comments go *outside* the item that they refer to.
/// They use the syntax /// to distinguish them from inner comments.
pub enum Test {
    Success,
    Fail(Error)
}

कन्वेंशनों

/// In documentation comments, you may use **Markdown**.
/// This includes `backticks` for code, *italics* and **bold**.
/// You can add headers in your documentation, like this:
/// # Notes
/// `Foo` is unsuitable for snafucating. Use `Bar` instead.
struct Foo {
    ...
}

/// It is considered good practice to have examples in your documentation
/// under an "Examples" header, like this:
/// # Examples
/// Code can be added in "fences" of 3 backticks.
///
/// ```
/// let bar = Bar::new();
/// ```
///
/// Examples also function as tests to ensure the examples actually compile.
/// The compiler will automatically generate a main() function and run the
/// example code as a test when cargo test is run.
struct Bar {
    ...
}

डॉक्यूमेंटेशन टेस्ट

प्रलेखन टिप्पणियों में कोड cargo test द्वारा स्वचालित रूप से निष्पादित किया जाएगा। इन्हें "प्रलेखन परीक्षण" के रूप में जाना जाता है, और यह सुनिश्चित करने में मदद करता है कि आपके उदाहरण काम करते हैं और आपके टोकरे के उपयोगकर्ताओं को भ्रमित नहीं करेंगे।

आप टोकरा जड़ से रिश्तेदार आयात कर सकते हैं (जैसे कि एक छिपे हुए extern crate mycrate; उदाहरण के शीर्ष पर)

/// ```
/// use mycrate::foo::Bar;
/// ```

यदि आपका कोड दस्तावेज़ीकरण परीक्षण में ठीक से निष्पादित नहीं हो सकता है, तो आप no_run विशेषता का उपयोग कर सकते हैं, जैसे:

/// ```no_run
/// use mycrate::NetworkClient;
/// NetworkClient::login("foo", "bar");
/// ```

आप यह भी संकेत कर सकते हैं कि आपके कोड को इस तरह से घबराना चाहिए :

/// ```should_panic
/// unreachable!();
/// ```