Sfenks'te, parametreleri bildirmekle birlikte belgelemenin bir yolu var mı?

Question

D.R.Y.

uygulamak için parametreyi bildirdiğim her satırın (gerektiği gibi) aynı satırda belgelenmesini tercih ederim. Bu gibi bir kod varsa:

def foo(
     flab_nickers, # a series of under garments to process 
     has_polka_dots=False, 
     needs_pressing=False # Whether the list of garments should all be pressed 
    ): 
    ... 

Yinelenmesini nasıl önleyebilirim doc dizesindeki parametreler ve parametre açıklamalarını koru?

Önlemek istiyorum:

def foo(
     flab_nickers, # a series of under garments to process 
     has_polka_dots=False, 
     needs_pressing=False # Whether the list of garments should all be pressed 
    ): 
    '''Foo does whatever. 

    * flab_nickers - a series of under garments to process 
    * needs_pressing - Whether the list of garments should all be pressed. 
     [Default False.] 

Python 2.6 veya python 3'te bir çeşit dekoratör manipülasyonu ile bu mümkün mü? Başka bir yolu var mı?

Answer 1

Bunu yapardım.

Bu koddan başlayarak.

def foo(
     flab_nickers, # a series of under garments to process 
     has_polka_dots=False, 
     needs_pressing=False # Whether the list of garments should all be pressed 
    ): 
    ... 

Ben fonksiyon parametre tanımlarını alır ve inşa eden bir ayrıştırıcı yazardı

aşağıdaki: Çeşitli argümanlar dize desen bazı oldukça düz ileri regex işleme var

def foo(
     flab_nickers, 
     has_polka_dots=False, 
     needs_pressing=False, 
    ): 
    """foo 

    :param flab_nickers: a series of under garments to process 
    :type flab_nickers: list or tuple 
    :param has_polka_dots: default False 
    :type has_polka_dots: bool 
    :param needs_pressing: default False, Whether the list of garments should all be pressed 
    :type needs_pressing: bool 
    """ 
    ... 

dokümantasyon şablonunda doldurmak için .

Çok iyi Python IDE'leri (örneğin PyCharm), varsayılan Sphinx param notasyonunu ve hatta IDE'nin bildirilen türle uyuşmadığını düşündüğü kapsamdaki varis/yöntemleri bile anlar.

Koddaki ek virgüllere dikkat edin; Bu sadece işleri tutarlı hale getirmek için. Zarar vermez ve gelecekte işleri basitleştirebilir.

Ayrıca ayrıştırma ağacı almak, gözden geçirmek ve güncelleme kodunu vermek için Python derleyicisini kullanmayı da deneyebilirsiniz. Bunu diğer diller için yaptım (Python değil), bu yüzden biraz biliyorum ama Python'da ne kadar iyi desteklendiğini bilmiyorum. Ayrıca, bu bir kerelik bir dönüşümdür.

İşlev tanımındaki orijinal satır içi yorumlar, DRY'yi gerçekten izlemez çünkü bu, gayri resmi bir dilde yapılan bir yorumdur ve en karmaşık araçlardan herhangi biri tarafından kullanılamaz.

Sfenks yorumları, RTS biçimlendirme dilinde oldukları için DRY'ye daha yakın olduğundan, docutils numaralı telefondan sıradan metin ayırma araçlarını kullanarak işlenmelerini çok daha kolaylaştırır.

Araçlar kullanabiliyorsa, yalnızca DRY var.

Faydalı linkler: https://pythonhosted.org/an_example_pypi_project/sphinx.html#function-definitions http://sphinx-doc.org/domains.html#id1

Answer 2

Bir önişlemci olmadan, yorum Python için bulunmaz gibi kaynak derlenmiştir kez bunu yapamaz. Kendinizi tekrarlamaktan kaçınmak için, yorumları kaldırın ve parametreleri yalnızca dokümanlar içinde belgeleyin, bu sizin argümanlarınızı belgelemenin standart yoludur.

Answer 3

Açıklamalar kısmen Python 3'te bu sorunu çözmek içindir:

http://www.python.org/dev/peps/pep-3107/

emin değilim henüz Sfenks'in bu uygulamada herhangi bir iş olmuşsa.