جمل التوثيق

جمل التوثيق
	فصل 7. الدوال

بيثون لديها ميزة أنيقة تدعى جمل (سلاسل) التوثيق (documentation strings) والتي يشار إليها عادة من خلال اسمها المختصرdocstrings. جمل التوثيق أداة هامة يجب عليك أن تستفيد منها حيث إنها تساعد على توثيق البرنامج بشكل أفضل، وتجعله أكثر سهولة للفهم. يمكننا حتى -ويا للعجب- من الحصول على جمل التوثيق من دالة مثلا بينما يعمل البرنامج بالفعل!

استخدام جمل التوثيق

مثال 7.8. استخدام جمل التوثيق

#!/usr/bin/python
# Filename: func_doc.py
def printMax(x, y):
	'''Prints the maximum of two numbers.
	The two values must be integers.'''
	x = int(x) # convert to integers, if possible
	y = int(y)
	if x > y:
		print x, 'is maximum'
	else:
		print y, 'is maximum'
printMax(3, 5)
print printMax.__doc__

الخرْج

$ python func_doc.py
5 is maximum
Prints the maximum of two numbers.
        The two values must be integers.

كيف يعمل

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

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

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

اذا كنت قد استخدمت help() في بيثون، فلابد أنك رأيت بالفعل استخدام جمل التوثيق. كل ما تفعله هو جلب خاصية __doc__ المنتمية لهذه الدالة وتعرضها لك بأسلوب أنيق. يمكنك تجربة ذلك على الدالة المبينة أعلاه - فقط أضِف help(printMax) في برنامجك. وتذكر أن تضغط مفتاح q للخروج من المساعدة.

توجد الأدوات مأتمتة يمكنها استحضار وثائق برنامجك بذات الطريقة. لذا، فإنني أنصح بشدة أن تستخدم جمل توثيق لأي دالة غير بديهية تكتبها. الأمر pydoc الذي يأتي مع توزيعة بيثون يعمل كمثل help() مستخدما جمل التوثيق.


الإفادة return		الخلاصة