- What is it?
- What does it do?
- Why does it do that?
- What is the API?
- What does it return?
- What are some examples of proper, real world usage (that don't involve foo/bar but instead, real world inputs/outputs I'd likely see)?
This could all easily fit in the top-level comments of a main() function or the help text of a CLI app.
- What is the API?
This could be gleaned from the code, either by reading it or by generating automatic documentation from it.
- What does it return?
This is commonly documented in function code.
- What are some examples of proper, real world usage (that don't involve foo/bar but instead, real world inputs/outputs I'd likely see)?
This is typically in comments or help text if it's a CLI app.