(original) (raw)

On Mon, Apr 15, 2013 at 8:17 PM, Maciej Fijalkowski <fijall@gmail.com> wrote:

> On Mon, Apr 15, 2013 at 9:56 AM, David Lam <david.k.lam1@gmail.com> wrote:

>> I tried to find an example in the source which addressed this, but
\>> found that the docstrings in similar cases to be largely duplicated.
\>> For instance, \_datetimemodule.c, decimal\_.c and \_json.c all seem to
\>> exhibit this docstring copy and pastage.
\>>
\>
\> Hi
\>
\> NumPy uses a hack to deal with this problem. It has a small C function
\> that would mutate the docstring under your feet. Personally I would
\> prefer some sort of tagging in C source that can copy-paste stuff
\> instead, honestly. It does sound like a good idea to share docstrings.
\> Seems also relatively trivial to write a test that checks that they
\> stay the same.

It's actually even worse than that - if a subclass overrides a method,
it has to completely duplicate the docstring, even if the original
docstring was still valid. So, for example, ABCs can't provide
docstrings for abstract methods.

So yeah, we end up not only duplicating between the C and Python
versions, but sometimes we end up duplicating between different
subclasses as well (datetime.datetime, datetime.date and datetime.time
are the worst offenders here).

I like the idea of at least adding a test that checks the Python
docstring and the C docstring are the same in the duplicated cases -
that should be a lot easier than adjusting the build process to let
the C version use the Python docstrings or vice-versa (even the
argument clinic DSL in PEP 434 doesn't try to achieve that - it just
tries to cut down on the duplication within the C code itself).