Learn Rust Coding · درس

تعليقات التوثيق

توثيق ///

تعليقات التوثيق درس مجاني في Learn Rust Coding على CoddyKit. هذا هو الدرس 3 من أصل 4. يمكنك قراءة الدرس كاملاً أدناه مجاناً — ثم تمرن عليه مباشرة في المتصفح باستخدام محرر أكواد مدمج ومدرس ذكاء اصطناعي متاح 24/7. هذا الدرس جزء من مسار التعلم في Learn Rust Coding، وتقدمك يتزامن عبر الويب وتطبيق CoddyKit. تتضمن دورة Learn Rust Coding 4 دروس في المجموع.

التوثيق في Rust

يوفّر Rust توثيقًا متكاملًا مع اللغة. وتتحول التعليقات الخاصة إلى توثيق HTML يُنشئه cargo doc.

تعليقات التوثيق الخارجية

استخدموا /// لتوثيق العنصر الذي يليه — مثل الدوال والبنى والتعدادات وغير ذلك. ويدعم النص Markdown.

/// Adds two numbers together.
pub fn add(a: i32, b: i32) -> i32 {
    a + b
}

تنسيق Markdown

تعرض تعليقات التوثيق Markdown: إذ تعمل العناوين والقوائم والنص العريض والروابط جميعًا. وتُستخدم العلامات الخلفية للشيفرة المضمّنة، وتبدأ عناوين الأقسام بالرمز #.

/// Computes the area of a rectangle.
///
/// # Arguments
/// * width - the width
/// * height - the height
pub fn area(width: u32, height: u32) -> u32 {
    width * height
}

أقسام التوثيق الشائعة

تجعل العناوين المتعارف عليها التوثيق سهل التصفح:

# Examples — أمثلة على الاستخدام
# Panics — الحالات التي تتسبب في الذعر
# Errors — الأخطاء التي تُرجعها الدالة
# Safety — الثوابت اللازمة للشيفرة غير الآمنة

تعليقات التوثيق الداخلية

استخدموا //! لتوثيق العنصر المحيط، ويكون عادةً وحدة أو الصندوق بأكمله. وضعوه في أعلى الملف.

//! # My Math Crate
//!
//! Utilities for basic arithmetic.

pub fn double(n: i32) -> i32 {
    n * 2
}

توثيق البنى والحقول

يمكن أن يكون لكل عنصر عام، بما في ذلك حقول البنى، تعليق توثيق خاص به.

/// A point in 2D space.
pub struct Point {
    /// The horizontal coordinate.
    pub x: f64,
    /// The vertical coordinate.
    pub y: f64,
}

إنشاء التوثيق

ينشئ cargo doc توثيق HTML في target/doc. أضيفوا --open لعرضه في متصفحكم.

cargo doc --open

استبعاد التبعيات

يوثّق Cargo تبعياتكم أيضًا بشكل افتراضي. استخدموا --no-deps لإنشاء توثيق لصندوقكم فقط.

cargo doc --no-deps --open

الروابط داخل التوثيق

اربطوا بالعناصر الأخرى بكتابة مسارها داخل أقواس مربعة. يحل Rust المسار وينشئ رابطًا قابلًا للنقر في التوثيق المُنشأ.

/// See also [add] for addition.
///
/// [add]: crate::add
pub fn subtract(a: i32, b: i32) -> i32 {
    a - b
}

لماذا نوثّق الشيفرة؟

يعود التوثيق الجيد بفوائد عديدة:

يُنشأ تلقائيًا بصيغة HTML قابلة للبحث
يُنشر مجانًا على docs.rs عند نشر صندوق
تُختبر الأمثلة الموجودة في التوثيق (اختبارات التوثيق)
يساعد أعضاء الفريق ويساعدكم مستقبلًا

توثيق وحدة

اجمعوا بين التعليقات الداخلية والخارجية: يبدأ ملف الوحدة بـ //! لوصف الوحدة، ويستخدم كل عنصر داخلها ///.

//! Geometry helpers.

/// Returns the perimeter of a square.
pub fn perimeter(side: f64) -> f64 {
    side * 4.0
}

تحقق سريع

ما صيغة التعليق التي توثّق العنصر الذي يأتي بعدها مباشرةً؟

مراجعة

لقد تعلمتم تعليقات التوثيق:

يوثّق /// العنصر التالي، بينما يوثّق //! العنصر المحيط
تدعم هذه التعليقات Markdown وأقسامًا مثل # Examples
تربط الروابط داخل التوثيق بين العناصر
ينشئ cargo doc --open توثيق HTML ويعرضه

الأسئلة الشائعة

هل درس «تعليقات التوثيق» مجاني؟

نعم — نص درس «تعليقات التوثيق» كامل متاح مجاناً هنا على الويب. لتمرينه بشكل تفاعلي (محرر أكواد مدمج ومدرس ذكاء اصطناعي متاح 24/7) وفتح باقي دورة Learn Rust Coding، انتقل إلى CoddyKit PRO. تتضمن دورة Learn Rust Coding 4 دروس في المجموع.

ماذا ستتعلم في «تعليقات التوثيق»؟

توثيق /// تتمرن على Learn Rust Coding مع أكواد عملية تشغلها مباشرة في المتصفح، ومدرس ذكاء اصطناعي متاح 24/7 يجيب على أسئلتك أثناء عملك.

هل أحتاج إلى خبرة سابقة لأبدأ Learn Rust Coding؟

لا تُشترط خبرة سابقة. Learn Rust Coding على CoddyKit منظم للمبتدئين حتى المتقدمين، لذا يمكنك البدء من هنا أو من البداية والتقدم بسرعتك الخاصة. هذا هو الدرس 3 من أصل 4.

كم من الوقت يستغرق درس «تعليقات التوثيق»؟

معظم دروس CoddyKit تستغرق حوالي 5–10 دقائق. كل منها موجز وتفاعلي، لذا تحرز تقدماً مستمراً وتستأنف من حيث توقفت عبر الويب والتطبيق.

هل يمكنني كتابة وتشغيل أكواد في درس Learn Rust Coding هذا؟

نعم. كل درس في Learn Rust Coding يتضمن محرر أكواد مدمج، لذا تكتب وتشغل أكواداً حقيقية مباشرة في متصفحك وتحصل على تعليقات فورية من الذكاء الاصطناعي — بدون إعداد محلي.

جميع الدروس في هذه الدورة

← العودة إلى Learn Rust Coding