Path: csiph.com!fu-berlin.de!uni-berlin.de!not-for-mail
From: Ian Kelly <ian.g.kelly@gmail.com>
Newsgroups: comp.lang.python
Subject: Re: Meta decorator with parameters, defined in explicit functions
Date: Sun, 3 Jul 2016 16:38:33 -0600
Lines: 39
Message-ID: <mailman.47.1467585556.2295.python-list@python.org>
References: <85mvm5vrbw.fsf@benfinney.id.au> <mailman.61.1467090177.2358.python-list@python.org> <21916e7b-9e19-4cef-94e0-bac331540ca2@googlegroups.com> <CALwzidn8DuSo-L2UQTJ7wZfzK+eHGzgGuy_ZfHFR9v4J_NHnjQ@mail.gmail.com> <mailman.15.1467436194.2295.python-list@python.org> <facf7142-25f5-4a8b-ab37-771884ab8d64@googlegroups.com> <CALwzid=GfLU8nbc5m4M9FxEO1ObWDTcvLJ3-wJXS0=w88-v8sw@mail.gmail.com> <mailman.33.1467521333.2295.python-list@python.org> <46690e10-1534-4f99-a40f-a148b4a21a27@googlegroups.com> <CALwzidmn-0TyxfKxcZoNoV5CgiFuOqRS_X=W34gSn5a-NVOy_w@mail.gmail.com> <mailman.38.1467546815.2295.python-list@python.org> <d2f71d72-d2da-4f68-9d6a-ca059327afdd@googlegroups.com> <CALwzid=ZsBnqjcMHVU6YQ17_993z01K3wKZ2QwZb9LKF_KJt_A@mail.gmail.com>
Mime-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: quoted-printable
In-Reply-To: <d2f71d72-d2da-4f68-9d6a-ca059327afdd@googlegroups.com>
Precedence: list
Xref: csiph.com comp.lang.python:111016

On Sun, Jul 3, 2016 at 3:17 PM, Lawrence D=E2=80=99Oliveiro
<lawrencedo99@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=E2=80=99Oliveiro wrote:
>>> That is a function that I am generating, so naturally I want to give it=
 a
>>> useful docstring. Am I =E2=80=9Cclobbering=E2=80=9D 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 =E2=80=9Cclobbering=E2=80=9D at all. Do you get that yet? =
My docstrings apply to *my* functions, not those supplied or generated by t=
he 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 actu=
ally
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.