توفر سلاسل توثيق Python (أو سلاسلها) طريقة ملائمة لربط التوثيق بوحدات Python والوظائف والفئات والطرق.
يتم تعريف docsting للكائن من خلال تضمين ثابت سلسلة كالبيان الأول في تعريف الكائن. تم تحديده في التعليمات البرمجية المصدر المستخدمة ، مثل التعليق ، لتوثيق جزء معين من التعليمات البرمجية.
على عكس تعليقات التعليمات البرمجية المصدر التقليدية ، يجب أن يصف docstring ما تفعله الوظيفة ، وليس كيف.
يجب أن تحتوي جميع الوظائف على سلسلة docstring وهذا يسمح للبرنامج بفحص هذه التعليقات في وقت التشغيل ، على سبيل المثال كنظام مساعدة تفاعلي أو بيانات وصفية.
يمكن الوصول إلى السلاسل من خلال السمة __doc__ على الكائنات.
كيف يجب أن يبدو شكل Docstring؟يجب أن يبدأ سطر سلسلة doc بحرف كبير وينتهي بنقطة. يجب أن يكون السطر الأول وصفًا موجزًا.
لا تكتب اسم الشيء. إذا كان هناك المزيد من الأسطر في سلسلة التوثيق ، فيجب أن يكون السطر الثاني فارغًا ، ويفصل الملخص بصريًا عن باقي الوصف.
يجب أن تكون الأسطر التالية عبارة عن فقرة واحدة أو أكثر تصف اصطلاحات استدعاء الكائن ، وآثاره الجانبية ، وما إلى ذلك.
مثال Docstringدعنا نوضح كيف يكون مثال على سلسلة وثيقة متعددة الأسطر:
def my_function():
"""Do nothing, but document it.
No, really, it doesn't do anything.
"""
pass
Code language: PHP (php)
دعونا نرى كيف سيبدو هذا عندما نطبعه
>>> print my_function.__doc__
Do nothing, but document it.
No, really, it doesn't do anything.
Code language: PHP (php)
إعلان الوثائقيُظهر ملف Python التالي إعلان سلاسل المستندات داخل ملف مصدر Python:
"""
Assuming this is file mymodule.py, then this string, being the
first statement in the file, will become the "mymodule" module's
docstring when the file is imported.
"""
class MyClass(object):
"""The class's docstring"""
def my_method(self):
"""The method's docstring"""
def my_function():
"""The function's docstring"""
كيفية الوصول إلى ملف Docstringفيما يلي جلسة تفاعلية توضح كيف يمكن الوصول إلى السلاسل
>>> import mymodule
>>> help(mymodule)
Code language: JavaScript (javascript)
بافتراض أن هذا هو ملف mymodule.py ، فإن هذه السلسلة ، كونها أول بيان في الملف ، ستصبح وحدات mymodule modules docstring عند استيراد الملف.
>>> help(mymodule.MyClass)
The class's docstring
>>> help(mymodule.MyClass.my_method)
The method's docstring
>>> help(mymodule.my_function)
The function's docstring
Code language: JavaScript (javascript)
المزيد من القراءة