Apa yang harus dimasukkan ke dalam modul python docstring? [Tutup]

Ok, jadi saya sudah membaca PEP 8 dan PEP 257 , dan saya sudah menulis banyak docstring untuk fungsi dan kelas, tapi saya sedikit tidak yakin tentang apa yang harus masuk dalam modul docstring. Saya pikir, paling tidak, harus mendokumentasikan fungsi dan kelas yang diekspor modul, tetapi saya juga melihat beberapa modul yang mencantumkan nama penulis, informasi hak cipta, dll. Apakah ada yang punya contoh tentang bagaimana seharusnya dokumentasi python yang baik terstruktur?

Pikirkan tentang seseorang yang melakukan help(yourmodule)apa yang diminta penerjemah interaktif - apa yang ingin mereka ketahui? (Metode lain untuk mengekstraksi dan menampilkan informasi kira-kira setara dengan helpdalam hal jumlah informasi). Jadi, jika Anda memiliki x.py:

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

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

kemudian:

>>> import x; help(x)

menunjukkan:

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)

Seperti yang Anda lihat, informasi terperinci tentang kelas (dan fungsinya juga, meskipun saya tidak menunjukkannya di sini) sudah termasuk dari dokumen komponen-komponen itu; dokumentasi modul itu sendiri harus menggambarkannya dengan sangat ringkas (jika sama sekali) dan lebih berkonsentrasi pada ringkasan singkat tentang apa yang dapat dilakukan modul secara keseluruhan untuk Anda, idealnya dengan beberapa contoh yang didokumentasikan (seperti fungsi dan kelas idealnya harus memiliki contoh yang didokumentasikan dalam dokumen mereka).

Saya tidak melihat bagaimana metadata seperti nama penulis dan hak cipta / lisensi membantu pengguna modul - ia bisa lebih suka berkomentar, karena bisa membantu seseorang mempertimbangkan apakah akan menggunakan kembali atau memodifikasi modul.

Mengutip spesifikasi :

Dokumentasi skrip (program yang berdiri sendiri) harus dapat digunakan sebagai pesan "penggunaan", dicetak ketika skrip dipanggil dengan argumen yang salah atau hilang (atau mungkin dengan opsi "-h", untuk "bantuan"). Dokstring semacam itu harus mendokumentasikan fungsi skrip dan sintaks baris perintah, variabel lingkungan, dan file. Pesan penggunaan bisa sangat rumit (beberapa layar penuh) dan harus cukup bagi pengguna baru untuk menggunakan perintah dengan benar, serta referensi cepat lengkap untuk semua opsi dan argumen untuk pengguna canggih.

Docstring untuk modul umumnya harus mencantumkan kelas, pengecualian dan fungsi (dan objek lain) yang diekspor oleh modul, dengan ringkasan satu baris masing-masing. (Ringkasan ini umumnya memberikan detail kurang dari garis ringkasan dalam dokumentasi objek). Doktring untuk paket (yaitu, dokumentasi __init__.pymodul paket ) juga harus mencantumkan modul dan sub-paket yang diekspor oleh paket.

Docstring untuk suatu kelas harus meringkas perilakunya dan mendaftar metode publik dan variabel instan. Jika kelas dimaksudkan untuk subkelas, dan memiliki antarmuka tambahan untuk subkelas, antarmuka ini harus dicantumkan secara terpisah (dalam dokumen). Konstruktor kelas harus didokumentasikan dalam docstring untuk __init__metodenya. Metode individual harus didokumentasikan dengan dokumentasi mereka sendiri.

Doktring fungsi atau metode adalah frasa yang berakhir dengan periode. Ini menetapkan efek fungsi atau metode sebagai perintah ("Lakukan ini", "Kembalikan itu"), bukan sebagai deskripsi; mis. jangan menulis "Mengembalikan nama path ...". Dokumentasi multiline untuk suatu fungsi atau metode harus meringkas perilakunya dan mendokumentasikan argumennya, nilai balik, efek samping, pengecualian yang muncul, dan batasan kapan bisa dipanggil (semua jika berlaku). Argumen opsional harus ditunjukkan. Ini harus didokumentasikan apakah argumen kata kunci adalah bagian dari antarmuka.