توثيق مشروع Rust: إنشاء وثائق عالية الجودة

تعلم Python بسهولة دون إرهاق نظري. حل مهام عملية مع التحقق التلقائي واكتب الكود مباشرة في المتصفح.

كتابة توثيق لمشروع Rust: من الأساسيات إلى التقنيات المتقدمة

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

أساسيات التوثيق في Rust

يستخدم Rust بناء جملة خاصًا للتوثيق، يعتمد على Markdown. يُكتب التوثيق باستخدام تعليقات التوثيق (doc-comments)، التي تبدأ بـ /// (للتوثيق الخارجي) أو //! (للتوثيق الداخلي للوحدات النمطية).

لنلقِ نظرة على مثال أساسي:

/// تحسب مضروب العدد (factorial).////// تأخذ هذه الدالة عددًا صحيحًا غير سالب `n`/// وتعيد مضروبه. إذا كانت `n` تساوي 0، يتم إرجاع 1.////// # أمثلة////// ```/// let result = factorial(5);/// assert_eq!(result, 120);/// ```pub fn factorial(n: u64) -> u64 {    (1..=n).product()}

//! # وحدة الدوال الرياضية//!//! تحتوي هذه الوحدة على العمليات الرياضية الأساسية،//! بما في ذلك حساب المضروب والمعاملات ذات الحدين.pub mod math;

توليد التوثيق باستخدام rustdoc

أداة rustdoc هي جزء من مجموعة أدوات Rust القياسية وتقوم تلقائيًا بتوليد توثيق HTML من تعليقات التوثيق. للتشغيل، يكفي تنفيذ الأمر:

cargo doc --open

يقوم هذا الأمر بتوليد التوثيق لمشروعك وجميع تبعياته، ثم يفتحه في المتصفح. يمكنك أيضًا تحديد علامات إضافية:

--no-deps — عدم تضمين توثيق التبعيات
--document-private-items — توثيق العناصر الخاصة
--target-dir — تحديد الدليل لملفات الإخراج

يتضمن التوثيق المُولَّد تلقائيًا التنقل والبحث وروابط للأنواع والدوال، بالإضافة إلى اختبارات من أمثلة الكود.

هيكل تعليقات التوثيق والأقسام الخاصة

يتبع التوثيق عالي الجودة في Rust هيكلًا معينًا. يُوصى باستخدام الأقسام التالية:

وصف مختصر — السطر الأول من التعليق، يظهر في القوائم والبحث
وصف تفصيلي — يشرح عمل الدالة وخصائصها وقيودها
# Examples — مثال أو أكثر على الاستخدام
# Panics — الحالات التي قد تسبب فيها الدالة حالة ذعر (panic)
# Errors — الأخطاء المحتملة وكيفية معالجتها
# Safety — للدوال غير الآمنة (unsafe): شرح الشروط المسبقة للسلامة

مثال على توثيق كامل لدالة:

/// تقسم السلسلة النصية إلى أجزاء بناءً على الفاصل المحدد.////// تعيد متجهًا من السلاسل النصية التي تم الحصول عليها بعد تقسيم/// السلسلة النصية الأصلية `text` عند كل ظهور لـ `delimiter`./// لا يتم تضمين السلاسل الفارغة في النتيجة.////// # أمثلة////// ```/// let result = split_string("a,b,c", ',');/// assert_eq!(result, vec!["a", "b", "c"]);/// ```////// # Panics////// تتعرض الدالة لحالة ذعر إذا كان `delimiter` سلسلة فارغة.////// # Errors////// لا تعيد هذه الدالة أخطاء، ولكنها قد تسبب حالة ذعر.pub fn split_string(text: &str, delimiter: char) -> Vec<String> {    assert!(delimiter != '\\0', "لا يمكن أن يكون الفاصل حرفًا فارغًا");    text.split(delimiter)        .filter(|s| !s.is_empty())        .map(|s| s.to_string())        .collect()}