สิ่งที่จะใส่ในโมดูลสตริงหลาม? [ปิด]

ตกลงดังนั้นฉันจึงอ่านทั้งPEP 8และPEP 257และฉันได้เขียนเอกสารจำนวนมากสำหรับฟังก์ชั่นและชั้นเรียน แต่ฉันไม่แน่ใจเกี่ยวกับสิ่งที่ควรไปในโมดูล docstring ฉันคิดว่าอย่างน้อยก็ควรทำเอกสารฟังก์ชั่นและคลาสที่โมดูลส่งออก แต่ฉันก็เห็นบางโมดูลที่แสดงรายชื่อผู้แต่งข้อมูลลิขสิทธิ์ ฯลฯ ใครบ้างมีตัวอย่างของวิธีการที่ดีงูหลาม docstring มีโครงสร้างหรือไม่

ลองนึกถึงคนที่กำลังทำhelp(yourmodule)ตามพรบ. ของล่ามแบบโต้ตอบ - พวกเขาต้องการทราบอะไรบ้าง (วิธีการอื่นในการแยกและแสดงข้อมูลนั้นมีความเท่าเทียมกันhelpในแง่ของปริมาณข้อมูล) ดังนั้นถ้าคุณมีx.py:

"""This module does blah blah."""

class Blah(object):
  """This class does blah blah."""

แล้ว:

>>> import x; help(x)

แสดงให้เห็นว่า:

Help on module x:

NAME
    x - This module does blah blah.

FILE
    /tmp/x.py

CLASSES
    __builtin__.object
        Blah

    class Blah(__builtin__.object)
     |  This class does blah blah.
     |  
     |  Data and other attributes defined here:
     |  
     |  __dict__ = <dictproxy object>
     |      dictionary for instance variables (if defined)
     |  
     |  __weakref__ = <attribute '__weakref__' of 'Blah' objects>
     |      list of weak references to the object (if defined)

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

ฉันไม่เห็นว่าข้อมูลเมตาเช่นชื่อผู้แต่งและลิขสิทธิ์ / ใบอนุญาตช่วยให้ผู้ใช้ของโมดูล - มันสามารถไปในการแสดงความคิดเห็นเพราะมันสามารถช่วยให้ใครบางคนพิจารณาว่าจะนำมาใช้ใหม่หรือปรับเปลี่ยนโมดูล

เพื่ออ้างคุณสมบัติ :

docstring ของสคริปต์ (โปรแกรมแบบสแตนด์อะโลน) ควรใช้งานได้เป็นข้อความ "การใช้งาน" ของมันซึ่งพิมพ์เมื่อสคริปต์ถูกเรียกด้วยอาร์กิวเมนต์ที่ไม่ถูกต้องหรือหายไป (หรืออาจมีตัวเลือก "-h" สำหรับ "ความช่วยเหลือ") docstring เช่นนี้ควรบันทึกการทำงานของสคริปต์และไวยากรณ์บรรทัดคำสั่งตัวแปรสภาพแวดล้อมและไฟล์ ข้อความการใช้งานอาจมีความละเอียดพอสมควร (หลายหน้าจอเต็ม) และควรเพียงพอสำหรับผู้ใช้ใหม่ในการใช้คำสั่งอย่างถูกต้องรวมถึงการอ้างอิงอย่างรวดเร็วโดยสมบูรณ์เกี่ยวกับตัวเลือกและอาร์กิวเมนต์ทั้งหมดสำหรับผู้ใช้ที่มีความซับซ้อน

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

docstring สำหรับคลาส ควรสรุปพฤติกรรมและรายการวิธีสาธารณะและตัวแปรอินสแตนซ์ หากคลาสนี้มีวัตถุประสงค์เพื่อเป็นคลาสย่อยและมีอินเทอร์เฟซเพิ่มเติมสำหรับคลาสย่อยอินเทอร์เฟซนี้ควรจะแสดงรายการแยกต่างหาก (ใน docstring) ตัวสร้างคลาสควรได้รับการบันทึกไว้ใน docstring สำหรับ__init__วิธีการ แต่ละวิธีควรมีเอกสารโดย docstring ของตนเอง

docstring ของฟังก์ชั่นหรือวิธีการ เป็นวลีที่ลงท้ายด้วยจุด มันกำหนดฟังก์ชั่นหรือผลกระทบของวิธีการเป็นคำสั่ง ("ทำสิ่งนี้", "กลับไปที่") ไม่ได้เป็นคำอธิบาย; เช่นอย่าเขียน "คืนชื่อพา ธ ... " multiline-docstring สำหรับฟังก์ชั่นหรือวิธีการควรสรุปพฤติกรรมและเอกสารข้อโต้แย้งของตนค่าตอบแทน (s) ผลข้างเคียงข้อยกเว้นยกขึ้นและข้อ จำกัด ในเมื่อมันสามารถเรียกได้ (ทั้งหมดถ้ามี) ควรระบุอาร์กิวเมนต์เพิ่มเติม ควรบันทึกไว้ว่าอาร์กิวเมนต์ของคำหลักเป็นส่วนหนึ่งของส่วนต่อประสานหรือไม่