On Sun, Jul 3, 2016 at 3:17 PM, Lawrence D’Oliveiro <lawrenced...@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. -- https://mail.python.org/mailman/listinfo/python-list
