Documenter ses fonctions (docstrings)
💁

Documenter ses fonctions (docstrings)

📑 Le petit mot du père MEVAERE

Si vous ne documentez pas vos programmes, le tout deviendra un gros bazar ingérable sur le long terme. Si vous souhaitez partager votre travail il est INDISPENSABLE de documenter votre code et dans ce petit article nous verrons comment documenter les fonctions.

❓ Qu'est-ce qu'un docstring ?

Déclarons une fonction

def mult_two(a: int, b: int) -> int:
    # your code here
    return a * b

Demandons de l'aide sur cette fonction

>>> help(mult_two)
Help on function mult_two in module __main__:
mult_two(a: int, b: int) -> int

>>> print(mult_two.__doc__)
None

‼ Comment je fais ?

Simplement on ajoute juste au dessous de la signature de la fonction, la documentation. Ici je n'indique pas les types car ils sont déjà définis dans la signature.

def mult_two(a: int, b: int) -> int:
    """Renvoie une multiplication de deux entiers

    Parameters
    ----------
    a : Premier entier
    b : Deuxième entier

    Returns
    -------
    int
        Multiplication des deux entiers
    """
		# your code here
    return a * b

🗂 Les différentes conventions possibles

Google Docstrings

"""Gets and prints the spreadsheet's header columns

Args:
    file_loc (str): The file location of the spreadsheet
    print_cols (bool): A flag used to print the columns to the console
        (default is False)

Returns:
    list: a list of strings representing the header columns
"""

reStructured Text

"""Gets and prints the spreadsheet's header columns

:param file_loc: The file location of the spreadsheet
:type file_loc: str
:param print_cols: A flag used to print the columns to the console
    (default is False)
:type print_cols: bool
:returns: a list of strings representing the header columns
:rtype: list
"""

NumPy/SciPy Docstrings

"""Gets and prints the spreadsheet's header columns

Parameters
----------
file_loc : str
    The file location of the spreadsheet
print_cols : bool, optional
    A flag used to print the columns to the console (default is False)

Returns
-------
list
    a list of strings representing the header columns
"""

Epytext

"""Gets and prints the spreadsheet's header columns

@type file_loc: str
@param file_loc: The file location of the spreadsheet
@type print_cols: bool
@param print_cols: A flag used to print the columns to the console
    (default is False)
@rtype: list
@returns: a list of strings representing the header columns
"""