راستدوك: دليل المبتدئين لتوثيق واجهة برمجة التطبيقات في راست

توفر الوثائق الجسر بين المطورين ومستخدمي التعليمات البرمجية الخاصة بهم. في نظام روست البيئي، ترفع الوثائق إلى مكانة رفيعة من خلالRustdoc، وهو أداة متقدمة لتوليد الوثائق تأتي مع توزيع روست القياسي. على عكس أدوات الوثائق في العديد من اللغات الأخرى، لا تقوم Rustdoc فقط بإنشاء وثائق ثابتة - بل تقوم بإنشاء مواقع ويب وثائقية تفاعلية، قابلة للاختبار، ومنسقة بشكل غني تعزز اكتشاف التعليمات البرمجية وسهولة الاستخدام.

لمطوري روست، توفر Apidog ميزات شاملة لوثائق واجهة برمجة التطبيقات (API) لـ HTTP APIs مع قدرات اختبار تفاعلية، وتنسيقات استجابة بصرية، ووظائف تعاونية.

تركز Apidog على توثيق نقاط النهاية، تنسيقات الطلب/الاستجابة، ومواصفات HTTP، بينما تتخصص Rustdoc في توثيق التعليمات البرمجية على مستوى اللغة - توثيق الهياكل، الوظائف، الخصائص، وغيرها من الإنشاءات البرمجية التي تشكل حزمة روست. تشترك كلا النظامين في الهدف الأساسي المتمثل في جعل الأنظمة التقنية المعقدة أكثر سهولة من خلال وثائق دقيقة وشاملة وسهلة الاستخدام.

ما هو Rustdoc؟

Rustdoc هو أداة سطر الأوامر تقوم بتحليل كود روست المصدر وتعليقات الوثائق الخاصة لإنشاء ملفات HTML وCSS وJavaScript التي تشكل موقع ويب وثائقي يمكن تصفحه. في جوهره، يعمل Rustdoc عن طريق استخراج تعليقات الوثائق من الكود الخاص بك وتحويلها إلى وثائق منظمة.

تشمل العملية الأساسية لـ Rustdoc:

1. تحليل ملفات كود روست لاستخراج تعليقات الوثائق
2. تحويل تلك التعليقات من Markdown إلى HTML
3. إنشاء هيكل موقع ويب قابل للبحث والتنقل
4. استخراج أمثلة التعليمات البرمجية من الوثائق وإعدادها للاختبار
5. إنشاء مراجع متقاطعة بين العناصر
6. إنتاج أصول ثابتة للوثائق النهائية

عند استدعاءه مباشرة، يقبل ملف Rustdoc المصدر كمدخل:

$ rustdoc src/lib.rs --crate-name my_crate

يقوم هذا الأمر بمعالجة ملف lib.rs ويخرج الوثائق إلى دليل doc بشكل افتراضي. الوثائق منظمة بشكل هرمى، مما يعكس هيكل الكود الخاص بك، مع صفحات منفصلة للوحدات، الهياكل، الأنماط، الخصائص، وغيرها من الإنشاءات في روست.

على الجانب الآخر، يعتمد Rustdoc على واجهات برمجة التطبيقات الداخلية لمترجم روست لتحليل وفهم الكود الخاص بك. هذه التكامل الوثيق مع المترجم يمكّن Rustdoc من إنشاء مراجع دقيقة، وتوثيق توقيعات النوع بشكل صحيح، والتحقق من أن أمثلة التعليمات البرمجية تقوم بالتجميع والتشغيل بشكل صحيح.

تعليقات الوثائق في روست

تعتمد الوثائق في روست على تركيبات التعليق الخاصة التي تختلف عن التعليقات العادية. هناك نوعان رئيسيان من تعليقات الوثائق:

تعليقات الوثائق الخارجية (///)

تقوم تعليقات الوثائق الخارجية بتوثيق العنصر الذي يليها وتُشار إليها بثلاث شرطات مائلة:

/// هذا تعليق وثائقي للدالة أدناه.
/// يمكن أن يتجاوز عدة أسطر ويدعم تنسيق Markdown.
pub fn documented_function() -> bool {
    true
}

تصف هذه التعليقات الوظائف، الهياكل، الأنماط، الخصائص، الوحدات، والعناصر الأخرى في قاعدة الكود الخاصة بك. تُسمى "تعليقات خارجية" لأنها موجودة خارج العنصر الذي توثقه.

تعليقات الوثائق الداخلية (//!)

تقوم تعليقات الوثائق الداخلية بتوثيق العنصر الذي تظهر فيه وتُشار إليها بـ //!:

//! توفر هذه الوحدة أدوات لتحليل ملفات التكوين.
//!
//! # أمثلة
//!
//! ```
//! let config = my_crate::config::parse("config.toml");
//! assert!(config.is_ok());
//! ```

pub fn parse(file_path: &str) -> Result<Config, ParseError> {
    // التنفيذ هنا
}

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

الفرق الفني بين أنماط التعليقات هذه دقيق ولكنه مهم: /// يوثق ما يأتي بعده، بينما //! يوثق ما يحتويه.

دعم Markdown في Rustdoc

تستخدم Rustdoc محلل Markdown متوافق مع CommonMark مع العديد من الامتدادات. هذا يمنح مؤلفي الوثائق إمكانية الوصول إلى مجموعة غنية من خيارات التنسيق:

التنسيق الأساسي

/// # المستوى 1
/// ## المستوى 2
///
/// يتم فصل الفقرات بواسطة أسطر فارغة.
///
/// *نص مائل* و **نص عريض** مدعوم.
///
/// - قوائم غير مرتبة
/// - يمكن إنشاؤها
/// - مثل هذا
///
/// 1. قوائم مرتبة
/// 2. تعمل أيضًا
///
/// `كود مباشر` محاط بعلامات اقتباس.

كتل التعليمات البرمجية

تعد كتل التعليمات البرمجية مهمة بشكل خاص في Rustdoc لأنها تخدم غرضين: تعرض أمثلة التعليمات البرمجية في الوثائق ويمكن استخراجها كاختبارات.

/// ```rust
/// // هذه كتلة كود
/// let x = 5;
/// assert_eq!(x, 5);
/// ```

بشكل افتراضي، إذا لم يتم تحديد لغة بعد ثلاثة علامات اقتباس، يفترض Rustdoc أن كتلة الكود تحتوي على كود روست. ومع ذلك، يمكنك تحديد لغات أخرى لتظليل التركيب اللغوي:

/// ```json
/// {
///     "name": "example",
///     "version": "1.0.0"
/// }
/// ```

امتدادات Rustdoc

تقوم Rustdoc بتوسيع CommonMark مع العديد من الميزات الإضافية:

نص مخطط

/// ~~نص مخطط~~ يستخدم ~.

الهوامش

/// هذه العبارة تحتاج إلى توضيح[^1].
///
/// [^1]: إليك التوضيح.

الجداول

/// | العنوان1 | العنوان2 |
/// |---------|---------|
/// | خلية1   | خلية2   |
/// | خلية3   | خلية4   |

قوائم المهام

/// - [x] المهمة المكتملة
/// - [ ] المهمة غير المكتملة

علامات الترقيم الذكية

تحول Rustdoc تلقائيًا تسلسلات علامات الترقيم ASCII إلى نظرائها Unicode:

• -- تصبح شرطة طويلة (–)
• --- تصبح شرطة طويلة (—)
• ... تصبح نقاط الحذف (…)
• تتحول الاقتباسات المستقيمة إلى اقتباسات منحنية

واجهة سطر أوامر Rustdoc التفصيلية

تقدم Rustdoc مجموعة شاملة من خيارات سطر الأوامر لتخصيص توليد الوثائق:

$ rustdoc --help

تشمل بعض الخيارات الأكثر أهمية من الناحية التقنية:

• --document-private-items: بشكل افتراضي، توثق Rustdoc العناصر العامة فقط. تتضمن هذه العلامة العناصر الخاصة في الوثائق، وهو ما يُفيد في الوثائق الداخلية.
• --test: تشغيل أمثلة الوثائق كاختبارات، يتحقق من أنها تقوم بالتجميع والتنفيذ كما هو متوقع.
• --test-args: تمرير معايير إضافية إلى مشغل الاختبار، مثل --nocapture لعرض الإخراج من الاختبارات.
• --edition=EDITION: تحديد إصدار روست لتحليل وتشغيل التعليمات البرمجية (2015، 2018، 2021، 2024).
• --target=TARGET: توليد وثائق للمنصة المستهدفة المحددة.
• --crate-type=TYPE: حدد نوع الحزمة للاختبارات (bin، lib، rlib، dylib، cdylib، staticlib، proc-macro).
• -L FLAG=PATH: أضف دليلاً إلى مسار بحث المكتبة، وهو أمر حاسم لحل الاعتماديات في الاختبارات.
• --cfg=SPEC: تمرير علامة --cfg إلى المترجم، مما يتيح ترجمة شرطية في كود الوثائق.
• --extern NAME=PATH: تحديد موقع حزمة خارجية، مما يسمح للاختبارات بالإشارة إلى اعتمادات خارجية.

بالنسبة لمشروع به اعتمادات خارجية، قد يبدو استدعاء Rustdoc نموذجيًا كما يلي:

$ rustdoc src/lib.rs --crate-name example_crate \
  --edition=2021 \
  -L dependency=target/debug/deps \
  --extern serde=target/debug/deps/libserde-abcd1234.rlib \
  --extern tokio=target/debug/deps/libtokio-efgh5678.rlib

من الجيد أن Cargo يقوم بأتمتة هذه العملية المعقدة مع أمر بسيط:

$ cargo doc --document-private-items

التكامل مع Cargo

يوفر Cargo واجهة مبسطة للعمل مع Rustdoc من خلال الأمر cargo doc. داخليًا، يقوم Cargo باستدعاء Rustdoc مع المعلمات المناسبة:

$ cargo doc --verbose

عند تشغيل هذا الأمر، سيتم عرض استدعاء Rustdoc الفعلي، موضحًا كيف يقوم Cargo بتكوين المسارات للاعتمادات ودلائل المخرجات.

تشمل الوظائف الأساسية:

• cargo doc: توليد مستندات للحزمة الحالية واعتمادياتها
• cargo doc --no-deps: توليد مستندات فقط للحزمة الحالية
• cargo doc --open: توليد مستندات وفتحها في متصفح ويب
• cargo doc --document-private-items: تضمين العناصر الخاصة في الوثائق
• cargo test --doc: تشغيل اختبارات الوثائق

يحدد Cargo بحكمة اسم الحزمة من ملف Cargo.toml الخاص بك، ويقوم بإعداد الهيكل الصحيح لدليل المخرجات تحت target/doc/، ويتأكد من ربط جميع الاعتمادات بشكل صحيح.

هيكل الوثائق وتنظيمها

توثيق مستوى الحزمة

يعمل توثيق مستوى الحزمة كنقطة هبوط لمكتبتك ويجب أن يوفر نظرة شاملة. يتم كتابة هذا كوثائق داخلية (//!) في أعلى ملف lib.rs:

//! # مكتبتي المتقدمة في التشفير
//!
//! توفر هذه الحزمة البدائل التشفيرية مع التركيز على:
//!
//! - **الأداء**: تنفيذات محسّنة لوحدات المعالجة المركزية الحديثة
//! - **الأمان**: خوارزميات تم التحقق منها رسميًا
//! - **سهولة الاستخدام**: واجهات برمجة تطبيقات عالية المستوى، صعبة الاستخدام الخاطئ
//!
//! ## بدء سريع
//!
//! ```rust
//! use crypto_lib::{Cipher, Mode};
//!
//! let key = crypto_lib::generate_key(256);
//! let cipher = Cipher::new(&key, Mode::GCM);
//!
//! let plaintext = b"رسالة سرية";
//! let ciphertext = cipher.encrypt(plaintext);
//! ```
//!
//! ## الميزات
//!
//! تدعم الحزمة الخوارزميات التالية:
//!
//! - AES (128، 192، 256)
//! - ChaCha20
//! - Poly1305
//! - HMAC
//! - PBKDF2

تشمل الوثائق الفعالة على مستوى الحزمة عادةً:

1. وصف مختصر، جملة واحدة عن غرض الحزمة
2. شرح مفصل عن المفاهيم الرئيسية والميزات
3. أمثلة بدء سريعة توضح الاستخدام الأساسي
4. نظرة عامة على الهيكل للمكتبات الأكثر تعقيدًا
5. علامات الميزات وخيارات التكوين
6. معلومات التوافق
7. خصائص الأداء

توثيق مستوى الوحدة

تعمل الوحدات كوحدات تنظيمية في روست ويجب أن تحتوي على وثائق خاصة بها توضح غرضها ومحتوياتها:

pub mod symmetric {
    //! خوارزميات التشفير المتماثل.
    //!
    //! توفر هذه الوحدة تنفيذات للتشفيرات الكتلية وتدفقات البيانات،
    //! خوارزميات التشفير الموثوقة، والأدوات ذات الصلة.
    //!
    //! # اعتبارات الأمان
    //!
    //! تم تدقيق جميع التنفيذات بواسطة [شركة الأمان]
    //! وتم التحقق منها رسميًا باستخدام [أداة التحقق].

    /// تنفيذ تشفير AES مع دعم المفاتيح بطول 128 و192 و256 بت.
    pub struct Aes {
        // الحقول هنا
    }

    // المزيد من العناصر...
}

توثيق مستوى العنصر

يجب أن تحتوي العناصر الفردية مثل الهياكل، الوظائف، والخصائص على وثائق مركزة توضح غرضها، واستخدامها، وأي اعتبارات خاصة:

/// مولد أرقام عشوائية آمن تكنولوجيًا.
///
/// يستخدم هذا CSPRNG مصدر الحظ في النظام لتوليد
/// بايت عشوائي مناسب للعملية التشفيرية.
///
/// # أمثلة
///
/// ```
/// use crypto_lib::CSPRNG;
///
/// let mut rng = CSPRNG::new();
/// let random_bytes = rng.generate_bytes(32);
/// ```
///
/// # الأمان
///
/// على نظام لينكس، يستخدم getrandom(2) عند توفره، ويتراجع إلى /dev/urandom.
/// على نظام ويندوز، يستخدم BCryptGenRandom.
/// على نظام macOS، يستخدم SecRandomCopyBytes.
pub struct CSPRNG {
    // تفاصيل التنفيذ
}

impl CSPRNG {
    /// ينشئ مولد عشوائي آمن تكنولوجيًا جديد.
    ///
    /// # انهيارات
    ///
    /// ينفجر إذا كان مصدر الحظ في النظام غير متاح.
    ///
    /// # أمثلة
    ///
    /// ```
    /// let rng = crypto_lib::CSPRNG::new();
    /// ```
    pub fn new() -> Self {
        // التنفيذ
    }

    /// يولد عددًا محددًا من بايت عشوائية.
    ///
    /// # المعاملات
    ///
    /// * `len` - عدد بايت العشوائية لتوليدها
    ///
    /// # الإرجاع
    ///
    /// مصفوفة تحتوي على `len` بايت عشوائية آمنة تكنولوجيًا.
    ///
    /// # أمثلة
    ///
    /// ```
    /// use crypto_lib::CSPRNG;
    ///
    /// let mut rng = CSPRNG::new();
    /// let key_material = rng.generate_bytes(32);
    /// assert_eq!(key_material.len(), 32);
    /// ```
    pub fn generate_bytes(&mut self, len: usize) -> Vec<u8> {
        // التنفيذ
    }
}

اختبارات الوثائق بعمق

واحدة من أقوى ميزات Rustdoc هي قدرتها على تشغيل أمثلة التعليمات البرمجية كاختبارات. وهذا يضمن أن:

1. أن الأمثلة في وثائقك تقوم فعلاً بالتجميع
2. أن الأمثلة تنتج النتائج المتوقعة
3. أن الأمثلة تبقى محدثة مع تطور واجهة برمجة التطبيقات الخاصة بك

عندما تتضمن كتلة كود روست في وثائقك، يقوم Rustdoc باستخراجها وإنشاء بنية اختبار حولها:

/// يضيف رقمين معًا.
///
/// # أمثلة
///
/// ```
/// let result = my_crate::add(2, 3);
/// assert_eq!(result, 5);
/// ```
pub fn add(a: i32, b: i32) -> i32 {
    a + b
}

خلف الكواليس، يقوم Rustdoc بتحويل هذا إلى ملف اختبار مستقل يبدو كالتالي:

extern crate my_crate;

fn main() {
    let result = my_crate::add(2, 3);
    assert_eq!(result, 5);
}

يتم بعد ذلك تجميع هذا الملف وتنفيذه. إذا تم تجميع البرنامج وتنفيذه بدون انفجار، فإن الاختبار ينجح.

معالجة الاختبار المسبق

قبل تشغيل الاختبار، يقوم Rustdoc بتطبيق العديد من التحويلات لجعل الأمثلة البسيطة أكثر ملاءمة:

1. التنبيهات الشائعة مثل unused_variables وdead_code مسموح بها
2. إذا لم تحتوي المثال على extern crate و#![doc(test(no_crate_inject))] لم تتحدد، يتم إدراج extern crate <mycrate>;
3. إذا لم تحتوي المثال على fn main، يتم لف الكود داخل fn main() { ... }

تسمح هذه التحويلات لك بالتركيز على الأجزاء المهمة من مثال دون ما يعرف بالإفراط في استخدام النموذج.

التحكم في سلوك الاختبار

يوفر Rustdoc عدة سمات للتحكم في كيفية تنفيذ الاختبارات:

• ignore: لا يتم اختبار الكود
• should_panic: يجب أن يتجمع الكود ولكنه ينفجر عند التنفيذ
• compile_fail: يجب ألا يتم تجميع الكود
• no_run: يتم تجميع الكود ولكن لا يتم تنفيذه
• edition2015, edition2018, edition2021: تشغيل الكود مع إصدار روست معين

أمثلة:

/// ```ignore
/// // هذا الكود لا يتم اختباره
/// let x = function_that_doesnt_exist();
/// ```
///
/// ```should_panic
/// // يجب أن ينفجر هذا الكود
/// panic!("تظهر هذه المثال زوبعة");
/// ```
///
/// ```compile_fail
/// // لا يجب أن يتجمع هذا الكود
/// let x: i32 = "يجب أن لا يتجمع هذا";
/// ```
///
/// ```no_run
/// // يتجمع هذا الكود ولكنه لا يعمل
/// loop {
///     println!("هذا سيعمل إلى الأبد!");
/// }
/// ```
///
/// ```edition2021
/// // يستخدم هذا الكود ميزات روست 2021
/// let result = try {
///     "10".parse::<i32>()?
/// };
/// ```

استخدام ? في اختبارات الوثائق

نظرًا لأن أمثلة الوثائق محاطة بدالة main() التي ترجع ()، يتطلب استخدام عامل ? معالجة خاصة. هناك طريقتان:

1. تعريف دالة main ترجع Result:

/// ```
/// # fn main() -> Result<(), std::io::Error> {
/// let content = std::fs::read_to_string("file.txt")?;
/// println!("محتوى الملف: {}", content);
/// # Ok(())
/// # }
/// ```

2. استخدام توضيح نوع مع Ok(()):

/// ```
/// let content = std::fs::read_to_string("file.txt")?;
/// println!("محتوى الملف: {}", content);
/// # Ok::<(), std::io::Error>(())
/// ```

في كلا الحالتين، يخفي الـ # في بداية بعض الأسطر تلك الخطوط من الوثائق المعروضة ولكنها تتضمنها في الاختبار.

الربط بالعناصر بالاسم

يوفر Rustdoc نظام مراجع قوية يسمح لمؤلفي الوثائق بإنشاء روابط لعناصر أخرى في قاعدة الكود. تعزز هذه الميزة بشكل كبير سهولة التنقل في الوثائق الخاصة بك.

الروابط داخل الوثائق

لإنشاء رابط لعناصر أخرى، استخدم التركيب [اسم_العنصر]:

/// يستخدم نوع [`HashMap`] من المكتبة القياسية.
///
/// يعتمد أيضًا على دالة [`build_map`] المعرفة في مكان آخر في هذه الحزمة.
pub fn process_data() {
    // التنفيذ
}

/// ينشئ [`HashMap`] جديد بقيم مسبقة.
pub fn build_map() -> HashMap<String, i32> {
    // التنفيذ
}

عندما يعالج Rustdoc هذه الروابط، فإنه يقوم تلقائيًا بحلها للعناصر الصحيحة، مما ينشئ روابط قابلة للنقر في HTML المولد.

تأهيل المسار

لرابط أكثر دقة، خاصة عند التعامل مع العناصر التي قد تحمل نفس الاسم في وحدات مختلفة، يمكنك استخدام المسارات المؤهلة بالكامل:

/// تستخدم هذه الدالة [`std::collections::HashMap`] للتخزين
/// و[`crate::utils::format`] لتنسيق الإخراج.
pub fn complex_operation() {
    // التنفيذ
}

يتبع حل المسار قواعد الرؤية في روست، لذا يمكنك الربط بالعناصر التي ستكون مرئية من النطاق الحالي فقط.

أهداف الروابط

يمكنك الربط بأنواع متنوعة من العناصر:

/// روابط لهيكل: [`MyStruct`]
/// روابط لنمط: [`Option`]
/// روابط لخاصية: [`Iterator`]
/// روابط لدالة: [`process_data`]
/// روابط لأسلوب: [`MyStruct::new`]
/// روابط لوحدة: [`crate::utils`]
/// روابط لثابت: [`MAX_SIZE`]
/// روابط لتوضيح النوع: [`Result`]

يسمح لك هذا النظام الشامل للروابط لمؤلفي الوثائق بإنشاء شبكة غنية من الوثائق المترابطة التي تساعد المستخدمين في التنقل عبر واجهات برمجة التطبيقات المعقدة.

ميزات الوثائق المتقدمة

سمة #[doc]

تقدم سمة #[doc] تحكمًا متقدمًا في توليد الوثائق:

// يعادل استخدام تعليقات /// 
#[doc = "هذه وثائق للعنصر أدناه."]
pub struct DocumentedStruct;

// إخفاء عنصر من الوثائق
#[doc(hidden)]
pub struct InternalStruct;

// إضافة أسماء مستعارة للبحث
#[doc(alias = "connection")]
#[doc(alias = "socket")]
pub struct NetworkStream;

للوثائق الشرطية بناءً على علامات الميزات:

/// تقوم هذه الدالة بأشياء رائعة.
#[doc = "شرح القدرة الأساسية."]
#[cfg_attr(feature = "advanced", doc = "تدعم أيضًا وضع متقدم عندما يتم تمكين ميزة 'advanced'.")]
pub fn do_things() {
    // التنفيذ
}

نماذج تضمين الوثائق

لإعادة استخدام المحتوى عبر الوثائق:

/// # سلامة
///
#[doc = include_str!("../docs/common_safety_notes.md")]
pub unsafe fn perform_unsafe_operation() {
    // التنفيذ
}

يسمح لك هذا بالحفاظ على مقاطع الوثائق الشائعة في ملفات منفصلة وتضمينها عند الحاجة، مما يقلل من التكرار ويضمن التناسق.

أمثلة مستخرجة

يمكن لـ Rustdoc تلقائيًا استخراج أمثلة التعليمات البرمجية من اختبارات الحزمة ودلائل الأمثلة الخاصة بك، مما يوفر سياقًا إضافيًا لاستخدام واجهة برمجة التطبيقات:

$ cargo doc --document-scraped-examples

تعمل هذه الميزة عن طريق فحص حزمة روست لديك للبحث عن استخدام العناصر العامة واستخراج تلك الاستخدامات كمثال. وهذا ذا قيمة خاصة لواجهات برمجة التطبيقات المعقدة حيث قد تكون أمثلة الوثائق المدمجة غير كافية.

الوثائق الشرطية

باستخدام سمات cfg، يمكنك تضمين أو استبعاد الوثائق بشكل شرطي:

#[cfg(target_os = "windows")]
/// تفاصيل تنفيذ محددة لنظام ويندوز.
pub fn windows_only_function() {
    // تنفيذ ويندوز
}

#[cfg(target_os = "linux")]
/// تفاصيل تنفيذ محددة لنظام لينكس.
pub fn linux_only_function() {
    // تنفيذ لينكس
}

يسمح لك هذا بإنشاء وثائق خاصة بالنظام الأساسي أو ميزة معينة تظهر فقط عند الحاجة.

HTML مخصص في الوثائق

لأغراض تنسيق خاصة، يسمح Rustdoc بتضمين HTML مباشرة في الوثائق:

/// <div class="warning">
/// <strong>تحذير:</strong> تقوم هذه الدالة بأداء عمليات الإدخال/الإخراج وقد تحجب.
/// </div>
pub fn blocking_operation() {
    // التنفيذ
}

مضافًا إلى CSS المخصص، يمكّن هذا تنسيقًا غنيًا يتجاوز ما يوفره Markdown فقط.

HTML وCSS مخصصين

يسمح Rustdoc بتخصيص مظهر الوثائق المولدة من خلال HTML وCSS:

معالجة HTML المسبق

يمكنك إضافة HTML مخصص إلى رأس الوثائق:

$ rustdoc src/lib.rs --html-in-header custom-header.html

هذا مفيد لإضافة أنماط مخصصة، مكتبات JavaScript، أو وسوم ميتا.

تخصيص CSS

لتطبيق CSS مخصص على وثائقك:

$ rustdoc src/lib.rs --css custom-styles.css

يمكن أن تستهدف ملفات CSS الخاصة بك هيكل HTML لـ Rustdoc لتخصيص الألوان، الخطوط، التخطيطات، والمزيد:

/* تغيير لون الخلفية الرئيسي */
body {
    background-color: #f5f5f5;
}

/* تنسيق كتل التحذير */
.warning {
    background-color: #fff3cd;
    border-left: 4px solid #ffc107;
    padding: 0.5rem 1rem;
    margin: 1rem 0;
}

/* تنسيق مخصص لكتل التعليمات البرمجية */
pre {
    background-color: #282c34;
    border-radius: 6px;
    padding: 1rem;
}

سمات التقديم المخصصة

يدعم Rustdoc العديد من السمات المدمجة، بما في ذلك الضوء، روست، الفحم، البحرية، وآيو. يمكنك أيضًا إنشاء سمات مخصصة:

$ rustdoc src/lib.rs --theme mytheme.css

أفضل ممارسات الوثائق

الدقة الفنية

يجب أن تكون الوثائق دقيقة من الناحية الفنية. حدد السلوك الفعلي، الحالات الحدية، وخصائص الأداء:

/// يبحث عن عنصر في شريحة مرتبة باستخدام البحث الثنائي.
///
/// # التعقيد
///
/// التعقيد الزمني: O(log n)
/// التعقيد المكاني: O(1)
///
/// # الانهيارات
///
/// ينفجر إذا لم تكن الشريحة مرتبة في ترتيب تصاعدي.
///
/// # أمثلة
///
/// ```
/// let sorted = [1, 2, 3, 4, 5];
/// assert_eq!(my_crate::binary_search(&sorted, 3), Some(2));
/// assert_eq!(my_crate::binary_search(&sorted, 6), None);
/// ```
pub fn binary_search<T: Ord>(slice: &[T], value: T) -> Option<usize> {
    // التنفيذ
}

الوثائق المهيكلة

اتبع هيكلًا متسقًا لكل نوع من العناصر:

الوظائف والأساليب:

• وصف قصير
• تفسيرات المعاملات
• وصف قيمة الإرجاع
• حالات الأخطاء
• قسم الانهيارات (إذا كان ذلك صالحًا)
• أمثلة
• خصائص الأداء
• اعتبارات الأمان (بالنسبة لوظائف unsafe)

الهياكل والأنماط:

• الغرض ووصف عام
• تفسيرات الحقول/الأنماط
• طرق الإنشاء
• العمليات الشائعة
• أمثلة على الاستخدام النموذجي

الخصائص:

• العقد والضمانات
• شرح طرق الضرورة
• توثيق الطرق المقدمة
• إرشادات التنفيذ
• أمثلة توضح التنفيذ والاستخدام

دقة اللغة

استخدم لغة تقنية دقيقة وتجنب الغموض:

• بدلاً من "سريع"، حدد "تعقيد زمني O(log n)"
• بدلاً من "فعال من حيث الذاكرة"، حدد "يستخدم مساحة مكدس ثابتة"
• بدلاً من "قد يفشل"، حدد شروط الخطأ الدقيقة
• بدلاً من "مدخلات كبيرة"، حدد قيودًا ملموسة

معلومات النسخ

وثق استقرارية واجهة برمجة التطبيقات واعتبارات النسخ:

/// يعالج حزم الشبكة وفقًا لـ RFC 1234.
///
/// # الاستقرارية
///
/// تُعتبر هذه الوظيفة مستقرة منذ النسخة 0.2.0.
///
/// # اختلافات النسخ
///
/// قبل النسخة 0.3.0، كانت هذه الوظيفة تقوم بشكل صامت بتقليص الحزم
/// الأكبر من 1500 بايت. الآن تعيد خطأ.
pub fn process_packet(packet: &[u8]) -> Result<ProcessedPacket, PacketError> {
    // التنفيذ
}

تقنيات الاختبار المتقدمة

الاختبار في بيئات مختلفة

يمكنك تكوين اختبارات الوثائق لتعمل مع متغيرات البيئة المحددة:

/// ```
/// # std::env::set_var("API_KEY", "test_key");
/// let client = my_crate::Client::new_from_env()?;
/// # Ok::<(), my_crate::Error>(())
/// ```

الاختبار مع الموارد الخارجية

للاختبارات التي تحتاج إلى موارد خارجية، استخدم سمة no_run وشرح المتطلبات:

/// ```no_run
/// // يتطلب هذا المثال قاعدة بيانات PostgreSQL على localhost:5432
/// // مع اسم المستخدم "test" وكلمة المرور "test"
/// let db = my_crate::Database::connect(
///     "postgres://test:test@localhost:5432/testdb"
/// )?;
/// # Ok::<(), my_crate::Error>(())
/// ```

اختبار معالجة الأخطاء

أظهر كيفية معالجة الأخطاء في واجهة برمجة التطبيقات الخاصة بك:

/// ```
/// use my_crate::{process_data, DataError};
///
/// // الحالة الناجحة
/// let result = process_data(&[1, 2, 3]);
/// assert!(result.is_ok());
///
/// // الحالة الخطأ
/// let error_result = process_data(&[]);
/// assert!(matches!(error_result, Err(DataError::EmptyInput)));
/// ```

التدويل وإمكانية الوصول

وثائق غير باللغة الإنجليزية

بينما لا يحتوي Rustdoc على دعم مدمج للتدويل، يمكنك توفير الوثائق بعدة لغات باستخدام علامات الميزات:

#[cfg(feature = "docs-en")]
/// يضيف رقمين معًا.
#[cfg(feature = "docs-es")]
/// Suma dos números.
#[cfg(feature = "docs-ja")]
/// 二つの数値を足します。
pub fn add(a: i32, b: i32) -> i32 {
    a + b
}

اعتبارات إمكانية الوصول

اكتب وثائق تكون قابلة للوصول إلى المستخدمين ذوي الإعاقات:

1. توفير بدائل نصية للصور
2. استخدام تباين لوني كاف
3. هيكلة المحتوى بعناوين مناسبة
4. جعل أمثلة التعليمات البرمجية متوافقة مع برامج قراءة الشاشة

/// توضح مخطط العمارة أدناه مكونات النظام:
///
/// ![مخطط العمارة](./images/architecture.png)
/// *نص بديل: مخطط يوضح تدفق البيانات من الإدخال عبر المعالجة إلى الإخراج،
/// مع مكونات قاعدة البيانات وذاكرة التخزين المؤقت على الجانبين*

الخاتمة

يعتبر Rustdoc أحد أقوى وأشمل أدوات الوثائق في أي نظام بيئي لبرمجة الكمبيوتر. إن تكامله الوثيق مع مترجم روست، وقدرات الاختبار القوية، وخيارات التنسيق الغنية تمكّن المطورين من إنشاء وثائق ليست فقط وصفية ولكن دقيقة، قابلة للاستخدام، وقابلة للصيانة.

من خلال الاستفادة من جميع إمكانيات Rustdoc - من تعليقات الوثائق الأساسية إلى الميزات المتقدمة مثل الترجمة الشرطية، HTML/CSS مخصص، والاختبار الشامل - يمكن لمطوري روست إنشاء وثائق تعمل كمرجع موثوق وكمورد تعلم.

تعد الوثائق جانبًا أساسيًا من تصميم واجهة برمجة التطبيقات وسهولة استخدام البرمجيات. عندما يتم إنشاؤها بعناية وبالدقة الفنية باستخدام قدرات Rustdoc، تصبح الأصل الذي لا يقدر بثمن والذي يقلل منحنى التعلم، ويمنع الأخطاء، ويعزز الاستخدام الصحيح لمكتباتك.

بينما يستمر نظام روست البيئي في التطور، يتطور Rustdoc معه، ويحسن دائمًا من قدراته لتلبية احتياجات مجموعة مستخدمين متزايدة التنوع والذكاء. من خلال إتقان Rustdoc، لا تحسن فقط قاعدة التعليمات البرمجية الخاصة بك، بل تسهم أيضًا في المعايير العالية للوثائق التي تساعد في جعل مجتمع روست واحدًا من أكثر المجتمعات ترحيبًا وقابلية للوصول في عالم البرمجة.

أسئلة متكررة

1. كيف يمكنني تصحيح اختبار الوثائق الفاشلة؟

الإجابة: يمكن تصحيح اختبارات الوثائق باستخدام عدة تقنيات:

تشغيل الاختبارات مع المزيد من المخرجات:

cargo test --doc -- --nocapture

إضافة عبارات طباعة للاختبار (ستكون مخفية في الوثائق ولكن مرئية أثناء تشغيل الاختبار):

/// ```
/// let result = my_crate::complex_function();
/// # println!("تصحيح: النتيجة = {:?}", result);
/// assert!(result.is_ok());
/// ```

استخدام علامة -test-args لتمرير خيارات إضافية:

cargo test --doc -- --test-args=--show-output

إنشاء نسخة مستقلة من اختبارك في ملف منفصل لتسهيل التصحيح.

إذا كنت تستخدم ميزات قد تؤثر على الاختبار، تأكد من تمكينها:

cargo test --doc --features=my-feature

2. كيف يمكنني توثيق التعليمات البرمجية غير الآمنة بشكل صحيح؟

الإجابة: يتطلب توثيق التعليمات البرمجية غير الآمنة اهتمامًا خاصًا بمتطلبات الأمان:

1. تأكد دائمًا من تضمين قسم "الأمان" مخصص يوضح جميع الثوابت التي يجب على المتصلين الالتزام بها.
2. التفصيل في السلوك غير المحدد الذي قد ينتج إذا لم يتم الالتزام بمتطلبات الأمان.
3. شرح لماذا يجب أن تكون الوظيفة غير آمنة ولا يمكن تنفيذها بأمان.
4. تقديم أمثلة تظهر كلاً من الاستخدام الصحيح والخاطئ (استخدم compile_fail للحالة الأخيرة).

مثال:

/// يقوم بتفكيك مؤشر خام.
///
/// # الأمان
///
/// يجب على المتصل التأكد من أن:
/// - المؤشر محاذي بشكل صحيح للنوع T
/// - يشير المؤشر إلى مثيل مبدئي من T
/// - المؤشر صالح للقراءة لحجم T
/// - لا توجد مراجع أخرى لنفس الذاكرة أثناء تشغيل هذه الوظيفة
///
/// يؤدي انتهاك أي من هذه الشروط إلى سلوك غير محدد.
///
/// # أمثلة
///
/// الاستخدام الآمن:
/// ```
/// let value = 42;
/// let ptr = &value as *const i32;
/// unsafe {
///     assert_eq!(my_crate::deref(ptr), 42);
/// }
/// ```
///
/// ```compile_fail
/// // سيؤدي هذا إلى سلوك غير محدد:
///