Come conoscere il tipo di ritorno della funzione e i tipi di argomento?

| | | | |

Anche se sono consapevole del concetto di digitazione anatra di Python, a volte ho difficoltà con il tipo di argomenti delle funzioni o il tipo del valore restituito della funzione.

Ora, se scrivessi la funzione da solo, conosco i tipi. Ma cosa succede se qualcuno vuole usare e chiamare le mie funzioni, come ci si aspetta che conosca i tipi? Di solito inserisco le informazioni sul tipo nella docstring della funzione (come: "...l'argomento id dovrebbe essere un intero..." e "... la funzione restituirà un ( string, [intero]) tupla.")

Ma cercare le informazioni nella docstring (e metterle lì, come programmatore) è davvero il modo in cui dovrebbe essere fatto?

Modifica: sebbene la maggior parte delle risposte sembri indirizzare verso "sì, documento!", penso che non sia sempre molto facile per i tipi "complessi".
Ad esempio : come descrivere concisamente in una docstring che una funzione restituisce un elenco di tuple, con ogni tupla della forma (node_id, node_name, uptime_minutes) e che gli elementi sono rispettivamente una stringa, una stringa e un intero?
La documentazione docstring PEP "non fornisce alcuna linea guida al riguardo.
Immagino che la controargomentazione sarà che in tal caso le classi dovrebbero essere usate, ma trovo python molto flessibile perché permette di passare queste cose usando liste e tuple, cioè senza classi.