Example 1 — Document a function for its callers
Show the steps and the answer
State the purpose in one line: 'Return the mean of a list of test scores.'
A caller first needs to know what the function is for, in their own terms, not how it loops.
Describe the input and output: 'scores: a list of numbers. Returns the mean as a decimal.'
The input and output are what callers depend on; naming the types stops someone passing in a string of digits.
Describe the unusual case: 'Returns None if scores is empty, instead of dividing by zero.'
Callers have to handle None, and they cannot know to unless it is written down; this is the line most often missing.
Add an example: average([70, 85, 90]) gives about 81.67, because 245 / 3 = 81.666...; average([]) gives None.
A worked example lets a reader check their understanding in seconds.
Answer: 'Return the mean of a list of test scores. scores: a list of numbers. Returns the mean as a decimal, or None if the list is empty. Example: average([70, 85, 90]) is about 81.67; average([]) is None.'
Takeaway: Function documentation covers purpose, inputs, output and the unusual cases, plus one example a reader can check.