[bordercases]

Many of these arguements are moot – because for any top-down function definition technique, the How to Design Programs recipe covers virtually all the bases.

- https://course.ccs.neu.edu/cs2500f18/design_recipe.html - https://cs110.students.cs.ubc.ca/reference/design-recipes.ht... - https://docs.racket-lang.org/htdf/index.html

Between a signature, purpose statement and examples, you've declared most of what documentation provides short of a longer contextual statement of the functions role in a codebase.

For larger modules there is How to Design Worlds.

- https://world.cs.brown.edu/1/htdw-v1.pdf

[threatofrain]

I wouldn't focus on the fact that the examples are on single functions. Libraries and frameworks are about API design and not individual atoms, and writing your documentation ahead of time is about crystalizing the API vision you have in your head.

One may have accidentally glossed over a critical design decision and this process can surface that.