Re: [matplotlib-devel] kwdoc processing with decorators

On Thu, Aug 13, 2009 at 10:12:23AM -0400, Darren Dale wrote:
> I appreciate how much time has gone into the patch, but this impacts
> so much code I think it is important to really nail the
> implementation. I think everything should be rolled up into a single
> high level decorator if possible. I offered a suggestion in the
> tracker. Consider:

> with_doc(*args, **kwargs):
>     mod_doc(f):
>         if args:
>             if not isinstance(args[0], str):
>                 # inherit docstring from first argument
>                 inherit = args.pop(0).__doc__
>                 if f.__doc__ is None:
>                     f.__doc__ = inherit
>                 else:
>                     f.__doc__ = inherit + '\n\n' +  f.__doc__
>         if kwargs:
>             # mapping interpolation
>             f.__doc__ = f.__doc__ % kwargs
>         if args:
>             try:
>                 # inserting
>                 f.__doc__ = f.__doc__ % args
>             except TypeError:
>                  # appending
>                  if f.__doc__ is None:
>                      f.__doc__ = ''
>                  f.__doc__ = f.__doc__ + '\n\n'+ '\n\n'.join(args)
>         return f
>     return mod_doc

I have not followed the conversation, so please forgive me if I am
talking bull**, but why are you not using functools.wraps? I have found
it is useful to make really sure that you are keeping all the
properties of a function that you want to decorate.

Gaël

PS: Some of the mayavi codebase should be changed to use wraps, so don't
take this as a blame, but more as a question :).