Python modülü öğretisine ne koyulur? [kapalı]

Tamam, ben de okumak ettik PEP 8 ve PEP 257 ve ben işlevleri ve sınıfları için Docstringler çok yazdım ama bir modül docstringe gitmeli hakkında biraz emin değilim. En azından modülün dışa aktardığı işlevleri ve sınıfları belgelendirmesi gerektiğini düşündüm, ancak yazar adlarını, telif hakkı bilgilerini vb. Listeleyen birkaç modül de gördüm. Herkesin iyi bir python öğretisinin nasıl olması gerektiğine dair bir örneği var mı? yapılandırılmış mı?

help(yourmodule)Etkileşimli tercümanın isteminde birisini yaptığını düşünün - ne bilmek istiyorlar ? (Bilgiyi elde etmenin ve göstermenin diğer yöntemleri, bilgi helpmiktarı bakımından kabaca eşdeğerdir ). Yani eğer varsa x.py:

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

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

sonra:

>>> import x; help(x)

gösterileri:

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)

Gördüğünüz gibi, sınıflarla ilgili ayrıntılı bilgiler (ve burada da bir tane göstermeme rağmen işlevler de) bu bileşenlerin doktrinlerinde zaten yer alıyor; modülün kendi öğretisi onları çok iyi bir şekilde tanımlamalı (eğer varsa) ve daha doğrusu, bir bütün olarak modülün sizin için neler yapabileceğinin kısa bir özetine odaklanmalı, ideal olarak bazı test edilmiş örneklerle (tıpkı işlevlerin ve sınıfların ideal olarak belgelenmiş örneklere sahip olması gerektiği gibi) onların öğretileri).

Yazar adı ve telif hakkı / lisans gibi meta verilerin modülün kullanıcısına nasıl yardımcı olduğunu görmüyorum - yorum yapmayı tercih edebilir, çünkü birisinin modülü yeniden kullanıp kullanmamayı veya değiştirmemeyi düşünmesine yardımcı olabilir.

Özellikleri alıntılamak için :

Bir komut dosyasının (tek başına çalışan bir program) öğretimi, komut dosyası yanlış veya eksik bağımsız değişkenlerle (veya "yardım" için "-h" seçeneğiyle) çağrıldığında yazdırılan "kullanım" iletisi olarak kullanılabilir olmalıdır. Böyle bir öğreti, komut dosyasının işlevini ve komut satırı sözdizimini, ortam değişkenlerini ve dosyaları belgelemelidir. Kullanım mesajları oldukça ayrıntılı olabilir (birkaç ekran dolu) ve yeni bir kullanıcının komutu düzgün bir şekilde kullanması için yeterli olması ve ayrıca sofistike kullanıcı için tüm seçeneklere ve argümanlara tam bir hızlı referans olması gerekir.

Bir modülün öğretisi , modül tarafından dışa aktarılan sınıfları, istisnaları ve işlevleri (ve diğer nesneleri) her birinin tek satırlık bir özetiyle listelemelidir. (Bu özetler genellikle nesnenin öğretisindeki özet satırından daha az ayrıntı verir.) Bir paketin öğretisi (yani paket __init__.pymodülünün öğretisi), paket tarafından verilen modülleri ve alt paketleri de listelemelidir.

Bir sınıfın öğretisi , davranışını özetlemeli ve genel yöntemleri ve örnek değişkenleri listelemelidir. Sınıfın alt sınıflara ayrılması amaçlanıyorsa ve alt sınıflar için ek bir arabirime sahipse, bu arabirim ayrı olarak listelenmelidir (doktora). Sınıf kurucusu, __init__yöntemi için doktora belgesinde belgelenmelidir . Bireysel yöntemler kendi doktorları tarafından belgelenmelidir.

Bir fonksiyonun veya yöntemin öğretisi, bir dönemle biten bir cümledir. İşlevin veya yöntemin etkisini bir komut olarak değil, komut olarak ("Bunu yap", "Geri ver") belirler; Örneğin "Yol adını döndürür ..." yazmayın. Bir işlev veya yöntem için çok satırlı bir öğreti, davranışını özetlemeli ve argümanlarını, dönüş değer (ler) ini, yan etkileri, ortaya çıkan istisnaları ve ne zaman çağrılabileceğine ilişkin kısıtlamaları belgelemelidir (varsa). İsteğe bağlı argümanlar belirtilmelidir. Anahtar kelime bağımsız değişkenlerinin arayüzün bir parçası olup olmadığı belgelenmelidir.