Cameron Simpson <c...@cskk.id.au> writes: > To answer my own question ... > > On 04Apr2019 14:05, Cameron Simpson <c...@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 -- https://mail.python.org/mailman/listinfo/python-list
