Zanurkuj w Pythonie/Dokumentowanie funkcji
Dokumentowanie funkcji
[edytuj]Funkcje można dokumentować wstawiając notkę dokumentacyjną (ang. doc string).
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.
Za pomocą potrójnych cudzysłowów ("""...""" ) możemy w łatwy sposób zdefiniować łańcuch znaków zawierający pojedyncze jak i podwójne cudzysłowy, podobnie jak w przypadku qq/../ w Perlu.
|
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.
Wiele pythonowych IDE wykorzystuje notki dokumentacyjne do "inteligentnej pomocy", czyli wyświetlania informacji (pobranej z notki dokumentacyjnej) o funkcji po wpisaniu jej nazwy. Może to stanowić dla nas nieocenioną pomoc, oczywiście pod warunkiem, że notki dokumentacyjne zostały przez nas zdefiniowane... |
Materiały dodatkowe
[edytuj]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