Dart Academy · درس

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

كتابة مستندات تظهر على pub.dev

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

التوثيق جزء من المنتج

تأتي الحزم الرائعة مع توثيق رائع. يحوّل Dart التعليقات الخاصة إلى مرجع قابل للتصفح، لذا فإن documentation ميزة أساسية وليست أمرًا ثانويًا. 📝

تعليقات التوثيق ذات الشرطات الثلاث

يبدأ تعليق التوثيق بثلاث شرطات مائلة. وتوضع هذه doc comments مباشرةً فوق تصريح، وتصف للمستخدمين ما يفعله.

/// Adds two numbers and returns the sum.
int add(int a, int b) => a + b;

ابدؤوا بسطر ملخّص واحد

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

يدعم Markdown

تقبل تعليقات التوثيق صيغة Markdown، لذا يمكنكم إضافة التأكيد والقوائم والروابط. وستبدو صفحتكم المُنسَّقة على pub.dev احترافية بجهد يكاد لا يُذكر.

/// Returns the **first** matching item.

الربط بالرموز الأخرى

أحاطوا اسمًا بقوسين مربعين لإنشاء cross-link تفاعلي. ويمكن للقراء الانتقال مباشرةً إلى الفئات أو الأساليب المرتبطة في التوثيق المُولَّد.

/// See [add] for the inverse of [subtract].

عينات الشيفرة في كتل مسوّرة

اعرضوا استخدامًا حقيقيًا داخل كتلة شيفرة مسوّرة في تعليقكم. يعلّم example قصير بسرعة أكبر من الفقرات، ويطمئن المستخدمين إلى أن الشيفرة تعمل.

وثّقوا كل عضو عام

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

توثيق على مستوى المكتبة

ضعوا تعليق توثيق فوق توجيه المكتبة لوصف الملف بأكمله. ويصبح هذا library comment النص التمهيدي لذلك الجزء من API لديكم.

/// Math helpers for everyday use.
library calc;

توليد الموقع باستخدام dartdoc

شغّلوا أداة dartdoc لتحويل تعليقاتكم إلى موقع ويب ثابت. ويشغّلها pub.dev نيابةً عنكم تلقائيًا عند النشر.

dart doc .

تغطية التوثيق تكسب نقاطًا

تكافئ pub.dev الحزم الموثّقة جيدًا. ترفع doc coverage الأعلى نتيجتكم، وتشير إلى الجودة لكل من يختار اعتمادية. ⭐

أبقوا التوثيق قريبًا من الشيفرة

بما أن تعليقات التوثيق توجد بجانب الشيفرة، فمن السهل تحديثهما معًا. تعاملوا مع docs القديمة كأنها خطأ وأصلحوها عند تغيّر السلوك.

تحقّق سريع

أي نمط من التعليقات يعامله Dart باعتباره تعليق توثيق؟

مراجعة: توثيق قابل للعرض

يمكنكم الآن كتابة doc comments ذات الشرطات الثلاث، وربط الرموز، وإضافة الأمثلة، وتوليد موقع باستخدام dart doc. التوثيق الواضح يكسب المستخدمين. 🙌

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

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

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

ماذا ستتعلم في «التوثيق باستخدام تعليقات dartdoc»؟

كتابة مستندات تظهر على pub.dev تتمرن على Dart Academy مع أكواد عملية تشغلها مباشرة في المتصفح، ومدرس ذكاء اصطناعي متاح 24/7 يجيب على أسئلتك أثناء عملك.

هل أحتاج إلى خبرة سابقة لأبدأ Dart Academy؟

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

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

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

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

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

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

← العودة إلى Dart Academy