Zanurkuj w Pythonie/Dokumentowanie funkcji

Dokumentowanie funkcji

Funkcje można dokumentować wstawiając notkę dokumentacyjną (ang. doc string).

Przykład. Definiowanie notki dokumentacyjnej w funkcji buildConnectionString

def buildConnectionString(params):
    """Tworzy łańcuch znaków na podstawie słownika parametrów.
    
    Zwraca łańcuch znaków.
    """
    return ";".join(["%s=%s" % (k, v) for k, v in params.items()])

Trzy następujące po sobie cudzysłowy wykorzystuje się do tworzenia ciągu znaków, który może zajmować wiele linii. Wszystko co się znajduje pomiędzy nimi tworzy pojedynczy łańcuch znaków; dotyczy to także znaków powrotu karetki (powrotu do początku linii) i cudzysłowu. Potrójne cudzysłowy możemy używać wszędzie, ale najczęściej wykorzystuje się je do tworzenia notek dokumentacyjnych.

Dzięki przedrostkowi u Python zapamięta ten łańcuch znaków w taki sposób, że będzie potrafił poprawnie zinterpretować polskie litery. Więcej szczegółów na ten temat dowiemy się w dalszej części tej książki.

W powyższym przykładzie wszystko pomiędzy potrójnymi cudzysłowami jest notką dokumentacyjną funkcji, czyli opisem do czego dana funkcja służy i jak ją używać. Notka dokumentacyjna, o ile istnieje, musi znaleźć się pierwsza w definicji funkcji (czyli zaraz po dwukropku). Python nie wymaga, aby funkcja posiadała notkę dokumentacyjną, lecz powinniśmy ją zawsze tworzyć. Ułatwia ona nam, a także innym, zorientowanie się w programie. Warto zaznaczyć, że notka dokumentacyjna jest dostępna jako atrybut funkcji nawet w trakcie wykonywania programu.

Materiały dodatkowe

Materiały co prawda w języku angielskim, ale na pewno warto je chociaż przejrzeć:

• PEP 257, na temat konwencji notek dokumentacyjnych.
• Sphinx - python documentation generator