Saya saat ini mulai dengan Python dan saya memiliki latar belakang PHP yang kuat dan dalam PHP saya telah terbiasa menggunakan javadoc
template dokumentasi.
Saya bertanya-tanya apakah javadoc
tempatnya sebagai docstring
dokumentasi dalam Python. Apa konvensi dan / atau guildeline resmi yang ada di sini?
Misalnya apakah sesuatu seperti ini terlalu rumit untuk dimasukkan ke dalam pola pikir Python atau haruskah saya mencoba untuk sesingkat mungkin?
"""
replaces template place holder with values
@param string timestamp formatted date to display
@param string priority priority number
@param string priority_name priority name
@param string message message to display
@return string formatted string
"""
Dan jika saya sedikit terlalu lengkap haruskah saya pergi dengan sesuatu seperti ini sebagai gantinya (di mana sebagian besar dokumentasi tidak bisa dicetak melalui __doc__
metode ini)?
# replaces template place holder with values
#
# @param string timestamp formatted date to display
# @param string priority priority number
# @param string priority_name priority name
# @param string message message to display
#
# @return string formatted string
def format(self, timestamp = '', priority = '', priority_name = '', message = ''):
"""
replaces template place holder with values
"""
values = {'%timestamp%' : timestamp,
'%priorityName%' : priority_name,
'%priority%' : priority,
'%message%' : message}
return self.__pattern.format(**values)
python
documentation
javadoc
docstring
JF Dion
sumber
sumber
Jawaban:
Lihatlah format reStructuredText (juga dikenal sebagai "reST"), yang merupakan format markup plaintext / docstring, dan mungkin yang paling populer di dunia Python. Dan Anda tentu harus melihat Sphinx , alat untuk menghasilkan dokumentasi dari reStructuredText (digunakan untuk misalnya dokumentasi Python itu sendiri). Sphinx mencakup kemungkinan untuk mengekstrak dokumentasi dari dokumen dalam kode Anda (lihat sphinx.ext.autodoc ), dan mengenali daftar bidang reST mengikuti konvensi tertentu. Ini mungkin menjadi (atau menjadi) cara paling populer untuk melakukannya.
Contoh Anda dapat terlihat sebagai berikut:
Atau diperluas dengan informasi jenis:
sumber
Replace template place holder with values.
bukanreplaces template place holder with values
- Perhatikan kalimat, huruf besar di awal, dan berhenti penuh (.) Di akhir.sphinx.ext.napoleon
ekstensi.Ikuti Google Python Style Guide . Perhatikan bahwa Sphinx juga dapat mem-parsing format ini menggunakan ekstensi Napolean , yang akan dikemas dengan Sphinx 1.3 (ini juga kompatibel dengan PEP257 ):
Contoh diambil dari dokumentasi Napolean yang ditautkan di atas.
Contoh komprehensif tentang semua jenis dokumen di sini .
sumber
Standar untuk string dokumentasi python dijelaskan dalam Python Enhancement Proposal 257 .
Komentar yang sesuai untuk metode Anda akan seperti
sumber
Lihatlah Documenting Python , halaman "yang ditujukan untuk penulis dan penulis potensial dokumentasi untuk Python."
Singkatnya, reStructuredText adalah apa yang digunakan untuk mendokumentasikan Python itu sendiri. Panduan pengembang berisi primer REST, panduan gaya, dan saran umum untuk menulis dokumentasi yang baik.
sumber