Python belgeleme dizeleri (veya belge dizgileri), Python modülleri, işlevleri, sınıfları ve yöntemleri ile belgelerin ilişkilendirilmesi için uygun bir yol sağlar.
Belirli bir kod segmentini belgelemek için kullanılan bir yorum gibi kullanılan kaynak kodda belirtilir. Geleneksel kaynak kodu yorumlarından farklı olarak, docstring işlevinin ne yaptığını açıklamalıdır.
Bir docstring nasıl görünmeli?
- docstring büyük harfle başlamalıdır.
- İlk satır kısa bir açıklama olmalıdır.
- docstring’de daha fazla satır varsa, ikinci satır boş olmalı, özeti görselin geri kalanından görsel olarak ayırmalısınız.
- Aşağıdaki satırlar, nesnenin arama kurallarını, yan etkilerini vb. açıklayan bir veya daha fazla paragraf olmalıdır.
Docstring Tanımlama:, yöntemin veya işlev bildiriminin hemen altında ''' yada """ ifadesiyle bildirilir. Tüm işlevlerin bir belge olması gerekir.
Docstring Ulaşım: Docstrings’e nesnenin __doc__ yöntemi kullanılarak veya yardım işlevini kullanarak erişilebilir.
Aşağıdaki örnek, bir dokümanın nasıl bildirileceğini ve erişileceğini göstermektedir.
|
1 2 3 4 5 6 7 8 9 10 11 |
def ornekfunc(): """Örnek bir fonksiyon olarak yapıldı.""" return None print ("Kullanımı __doc__:") print (ornekfunc.__doc__) print ("help kullanımı:") help(ornekfunc) |
Çıktı:
Tek Satırlı Docstring
Adından da anlaşılacağı gibi, tek satırlık bir satır dizgisi bir çizgiye sığar. Belli durumlarda kullanılırlar. Kapanış teklifleri açılış fiyatları ile aynı çizgide. Bu tek gömlekler için daha iyi görünüyor.
Örneğin:
|
1 2 3 4 5 6 7 8 |
def power(a, b): """a taban, b ise üssü gösterir""" return a**b print (power.__doc__) |
Çok Satırlı Docstring
Çok satırlı docstring’ler, tek satırlık bir belgesel gibi bir özet satırından oluşur, ardından boş bir çizgi izler ve ardından daha ayrıntılı bir açıklama gelir. Özet satırı, açılış fiyat teklifi ile aynı satırda veya bir sonraki satırda olabilir.
Aşağıdaki örnek çok satırlı bir dokuyu göstermektedir.
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 |
def my_function(arg1): """ Özet satorı Fonksiyon tanımı Parameters: arg1 (int): arg1 tanımı Returns: int: Dönüş değeri tanımı """ return arg1 print (my_function.__doc__) |
1 Yorum