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 help
dalam 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.
help()
metode ini dalam juru bahasa daripada pengguna yang hanya membaca kode.Mengutip spesifikasi :
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.
sumber