Documentation Comments लिखना
In this page:
/// Documents the next item
//! Documents the enclosing item
/// # Examples
/// # PanicsDocumenting a Function with ///
किसी function के ऊपर सीधे /// comments रखना describe करता है कि यह क्या करता है, और cargo doc उस function की documentation page generate करने के लिए यह text उपयोग करता है।
उदाहरण: Documenting a Function with ///
/// Calculates the area of a rectangle given its width and height.
fn area(width: f64, height: f64) -> f64 {
width * height
}
fn main() {
println!("Area: {}", area(3.0, 4.0));
}Login to try C/C++/Java/PHP code in the editor
Documenting a Module with //!
//! comments, आमतौर पर किसी file के बिल्कुल top पर रखे गए, enclosing item को खुद document करते हैं (जैसे पूरा module) बजाय उनके बाद आने वाले किसी भी code के।
उदाहरण: Documenting a Module with //!
//! This module provides simple geometry helper functions.
fn perimeter(width: f64, height: f64) -> f64 {
2.0 * (width + height)
}
fn main() {
println!("Perimeter: {}", perimeter(3.0, 4.0));
}Login to try C/C++/Java/PHP code in the editor
Including a Usage Example
अच्छी documentation comments में अक्सर एक fenced code example शामिल होता है जो दिखाता है कि function कैसे call करें, जो readers के लिए helpful भी है और अपने आप चलने वाले doc test के रूप में भी काम करता है।
उदाहरण: Including a Usage Example
/// Converts Celsius to Fahrenheit.
///
/// ```
/// let f = my_project::to_fahrenheit(0.0);
/// assert_eq!(f, 32.0);
/// ```
pub fn to_fahrenheit(celsius: f64) -> f64 {
celsius * 9.0 / 5.0 + 32.0
}
fn main() {
println!("{}", to_fahrenheit(0.0));
}Login to try C/C++/Java/PHP code in the editor
Generating HTML Docs
cargo doc --open किसी project की सभी doc comments से एक पूरी HTML documentation site build करता है और इसे सीधे आपके web browser में खोलता है।
उदाहरण: Generating HTML Docs
cargo doc --open⚠️ Run this in your own terminal or Node.js environment.
- Regular
//comments उपयोग करना जब///चाहिए ताकि comment असल मेंcargo docसे documentation के रूप में उठाया जाए। - यह भूल जाना कि
//!enclosing item को document करता है (जैसे पूरा module) बजाय इसके बाद आने वाले अगले item के। - Public functions के लिए doc comments में एक runnable example include न करना, एक free doc test का आसान मौका गंवाते हुए।
///इसके तुरंत बाद आने वाले item को document करता है, जैसे एक function या struct।//!enclosing item को खुद document करता है, आमतौर पर किसी module या crate के top पर उपयोग होता है।cargo doc --openइन comments से HTML documentation generate करता है और इसे एक browser में खोलता है।- अच्छी तरह लिखी doc comments में अक्सर एक runnable example शामिल होता है, जो एक doc test के रूप में भी काम करता है।
Chapter Quiz — Complete all 8 topics to unlock
0/8 topics done
Complete these topics first: