سلاسل التوثيق النصية في بايثون
يمكن أن تكون العبارة الأولى في كتلة الدالة سلسلة نصّية، وتمثّل سلسلة التوثيق النصية الخاصة بتلك الدالة ويطلق عليها أيضًا تسمية docstring.
هناك أدوات تستخدم سلاسل التوثيق النصية لإنتاج توثيق عبر شبكة الإنترنت، أو تسمح للمستخدم بتصفح الشيفرة بصورة تفاعلية؛ لذا ينصح باستخدام سلاسل التوثيق النصية في الشيفرة التي تكتبها.
يجب أن يكون السطر الأول قصيرًا ومقتضبًا ويقدّم لمحة مختصرة عن الغرض من إنشاء الكائن، ولأجل الاختصار يجب أن لا يتضمن السطر الأول اسم الكائن أو نوعه؛ فهناك وسائل أخرى للتصريح عن ذلك (باستثناء الحالة التي يكون فيها الاسم فعلًا يصف عمل الدالة). يجب أن يبدأ هذا السطر بحرف كبير وينتهي بنقطة.
في حال تضمّنت سلسلة التوثيق النصية أكثر من سطر واحد، يجب أن يكون السطر الثاني حنيئذٍ فارغًا بحيث يكون الملخص مفصولًا عن وصف الدالة والذي يتضمّن فقرة واحدة أو أكثر تصف طريقة استدعاء الكائن والنتائج المترتبة على هذا الاستدعاء ...إلخ.
لا يزيل مفسّر بايثون الإزاحات من سلاسل التوثيق النصية ذات الأسطر المتعددة، لذا يجب على الأدوات التي تعالج التوثيق إزالة الإزاحات حسب الحاجة، ويتم ذلك بالأسلوب التالي:
- يحدد أول سطر فارغ بعد السطر الأول في سلسلة التوثيق النصية مقدار الإزاحة للتوثيق بأكمله. (لا يمكن استخدام السطر الأول في سلسلة التوثيق لأنّه يأتي مباشرة بعد علامات الاقتباس؛ لذا لا يمكن تحديد مقدار الإزاحة من هذا السطر).
- يزيل المفسّر من بداية جميع الأسطر في سلسلة التوثيق مسافات بيضاء تكافئ مقدار الإزاحة، ويجب أن لا تكون هناك أسطر تمتلك إزاحة أقل من الإزاحة المحدّدة، وإن حدث ذلك فإنّ جميع المسافات البيضاء ستحذف من بداية السطر. يجب اختبار تساوي المسافات البيضاء بعد توسيع علامات الجدولة (إلى 8 مسافات عادة).
مثال
فيما يلي مثال على سلسلة توثيق نصية ذات أسطر متعددة:
>>> def my_function():
... """Do nothing, but document it.
...
... No, really, it doesn't do anything.
... """
... pass
...
>>> print(my_function.__doc__)
Do nothing, but document it.
No, really, it doesn't do anything.
مصادر
- صفحة More Control Flow Tools في توثيق بايثون الرسمي.