chapter11

Automatyczne dokumentowanie

Przykład 10.5: docstring

#!/usr/bin/env python
# -*- coding: utf-8 -*-

def printMax(x, y):
    '''\
Wypisuje maksymalną liczbę spośród dwóch podanych.

Obydwie wartości muszą być liczbami całkowitymi.'''
    x = int(x) # Zmienia na liczby całkowite, jeżeli to możliwe.
    y = int(y)

    if x > y:
        print(x, 'to maksimum')
    else:
        print(y, 'to maksimum')

printMax(3, 5)
print(printMax.__doc__)
#help(printMax)

Objaśnienie:

Opis w postaci łańcucha znaków w pierwszym wierszu funkcjito jej DocString (opis dokumentujący). Taki sam opis można zastosować do modułów i klas!

Zaleca się (choć nie jest to obowiązkowe), aby opis docstring zaczyna… się dużą literą, pierwszy wiersz był zakończony kropką, po nim następował wiersz pusty, a dalej dokładniejsze wyjaśnienia.

Opis (docstring) jest dostepny za pośrednictwem własności doc (uwaga na podwójne podkreślenia). W Pythonie wszystko jest obiektem - także nawet funkcje – dlatego można definować własności funkcji (takie jak +doc).

Zamiast odwołania do doc można używać funkcji help(). W tym wypadku help(printMax).