docstrings done right

Docs should:

• Describe the algorithm
• Give usage-examples
• Give instructions on how to use function
• Use-Cases?
• Alternatives?
• Motivation?

If you describe as much as possible via formal languages, tools can read them too and help you. It also removes ambiguities. 

You could use:

• TLA+ to describe the algorithm
• Usage-examples via doctests in form of unit-tests
• Instructions on how to use the function via DbC: Pre-Conditions, Post-Conditions and Invariants (the blend into the algorithm-description of TLA+

The docstrings are parsed and a documentation is created while using the new power gained by the tools (maybe create a playground, etc.)