Python Docstrings

เราสามารถแสดงความคิดเห็นโค้ดในโปรแกรม python เพื่อทำความเข้าใจส่วนต่างๆ ของโค้ดได้ แต่หากต้องการค้นหาความคิดเห็นและส่วนต่างๆ ของความคิดเห็น เราจำเป็นต้องใช้การค้นหา (CTL+F) และเลื่อนดูหลายบรรทัด นอกจากนี้ เรายังไม่มีวิธีรู้ในทันทีว่าคำใดเชื่อมโยงกับจำนวนส่วนของรหัส เป็นต้น เพื่อแก้ปัญหานี้ เรามี python Docstring ซึ่งเข้าถึงสตริงทันทีหลังจากนิยามฟังก์ชัน โมดูล คลาส หรือเมธอด

พิมพ์เอกสาร

แอตทริบิวต์ __doc__ จะเชื่อมโยงกับชื่อของอ็อบเจ็กต์ python โดยอัตโนมัติเมื่อ si ประกาศทันทีหลังคำจำกัดความของอ็อบเจ็กต์นั้น ด้านล่างนี้เป็นตัวอย่างที่ให้ความกระจ่าง

ตัวอย่าง

def Add_nums(x):
   '''Ada a number to itself.'''
   return x + x
print(Add_nums.__doc__)

ผลลัพธ์

การเรียกใช้โค้ดข้างต้นทำให้เราได้ผลลัพธ์ดังต่อไปนี้ -

Ada a number to itself.

เอกสารบรรทัดเดียวเทียบกับเอกสารหลายบรรทัด

เอกสารบรรทัดเดียวมีบรรทัดเดียวและไม่ควรอธิบายมากเกินไป อยู่ภายในเครื่องหมายคำพูดสามตัวที่จุดเริ่มต้นและจุดสิ้นสุดของสตริง ตัวอย่างข้างต้นเป็น docstring บรรทัดเดียว

เอกสารหลายบรรทัด

บางครั้งเราอาจต้องอธิบายโมดูลหรือฟังก์ชันโดยละเอียด ในกรณีนั้น เราใช้ docstring แบบหลายบรรทัด โดยจะแสดงบรรทัดสรุปเช่นเดียวกับเอกสารสตริงหนึ่งบรรทัด แล้วตามด้วยบรรทัดว่าง ตามด้วยคำอธิบายที่ละเอียดยิ่งขึ้น

ตัวอย่าง

def Fibonacci(n):
   '''The Fibonacci numbers are the numbers in the following integer sequence.
0, 1, 1, 2, 3, 5, 8, 13, 21, 34, 55, 89, 144, .'''
   return x + x
print(Fibonacci.__doc__)

ผลลัพธ์

การเรียกใช้โค้ดข้างต้นทำให้เราได้ผลลัพธ์ดังต่อไปนี้ -

The Fibonacci numbers are the numbers in the following integer sequence.
0, 1, 1, 2, 3, 5, 8, 13, 21, 34, 55, 89, 144, .

Docstring ของวัตถุ Python ที่สร้างขึ้น

เราสามารถเข้าถึงเอกสารที่เกี่ยวข้องกับอ็อบเจ็กต์ python เช่น ฟังก์ชัน โมดูล ฯลฯ ได้อย่างง่ายดายโดยใช้ชื่อคลาสร่วมกับ __doc__

ตัวอย่าง

print(list.__doc__)

ผลลัพธ์

การเรียกใช้โค้ดข้างต้นทำให้เราได้ผลลัพธ์ดังต่อไปนี้ -

Built-in mutable sequence.

If no argument is given, the constructor creates a new empty list.
The argument must be an iterable if specified.

เยื้องใน Docstrings

การเยื้องใดๆ ในบรรทัดแรกของ docstring (เช่น จนถึงบรรทัดแรก) จะไม่มีนัยสำคัญและถูกลบออก การเยื้องสัมพัทธ์ของบรรทัดต่อมาใน docstring ยังคงอยู่ เอกสารประกอบการเยื้องเหมือนกับเครื่องหมายคำพูดที่บรรทัดแรก