Meta decorator with parameters, defined in explicit functions

[Ian Kelly]

On Sun, Jul 3, 2016 at 3:17 PM, Lawrence D’Oliveiro
<lawrencedo99 at gmail.com> wrote:
> On Sunday, July 3, 2016 at 11:53:46 PM UTC+12, Ian wrote:
>> On Sat, Jul 2, 2016 at 11:37 PM, Lawrence D’Oliveiro wrote:
>>> That is a function that I am generating, so naturally I want to give it a
>>> useful docstring. Am I “clobbering” any objects passed in by the caller,
>>> or returned by the caller? No, I am not.
>>
>> It isn't useful, though. If somebody writes a docstring for a
>> function, it's because they want that to be the docstring for the
>> function ...
>
> Which I am not “clobbering” at all. Do you get that yet? My docstrings apply to *my* functions, not those supplied or generated by the caller.

Sorry, but you're the one who doesn't seem to get it. Because it's a
decorator, "your" function is replacing the caller's function in the
caller's namespace. If the docstring written in the code for function
m.f is x, but the value of m.f.__doc__ is actually y, then the
docstring x is, for all practical purposes, clobbered. That you're not actually
modifying the original function is irrelevant.

For the purpose of the built-in help, it's the value of m.f.__doc__
that counts. For the purpose of documentation built with pydoc, it's
the value of m.f.__doc__ that counts. If the documentation for every
decorator in a module just reads "generates a decorator which applies
<function name> to the given arguments", that's useless documentation.

Which brings me to the other half of the point I was trying to make:
your decorator_with_args doesn't even *need* a docstring. It's not
part of the public interface. As a nested function that doesn't have
its own name within the module, help() or pydoc won't even include it
in their output. If you want to put something in the code to explain
what it does, that's fine, but use a comment for that. The docstring
doesn't add any value.