formatted docstrings

[Ben Finney]

Cameron Simpson <cs at cskk.id.au> writes:

> To answer my own question ...
>
> On 04Apr2019 14:05, Cameron Simpson <cs at cskk.id.au> wrote:
> > Is it unreasonable to promote bare format strings as candidates for
> > the docstring?
>
> Sigh. Because such a string _should_ be evaluated in the runtime scope
> context of the _called_ function, and it hasn't been called.

Another reason why docstrings should only be literals: a common use case
is to evaluate the docstrings and put them into static reference
documentation.

If there's something about the API that will be different depending on
where the API is running, but the API documentation just shows me some
condition from when the documentation was built, that's a nasty surprise
waiting to happen.

Instead, the docstring should just explicitly describe the domain of
possible values (or whatever it is that's going to change depending on
the environment).

-- 
 \          “Courage is not the absence of fear, but the decision that |
  `\     something else is more important than fear.” —Ambrose Redmoon |
_o__)                                                                  |
Ben Finney