On Thu, Aug 13, 2009 at 7:44 AM, John Hunter<jdh2...@gmail.com> wrote:
> On Wed, Aug 12, 2009 at 7:12 AM, John Hunter<jdh2...@gmail.com> wrote:
>> Those of you with an interest in mpl docstring processing may want to
>> comment on this tracker item
>>
>> https://sourceforge.net/tracker/index.php?func=detail&aid=2835685&group_id=80706&atid=560720
>
> This patch has come a long way since initial submission, and I am
> personally +1 on it, but it is wide reaching in the code and I'd like
> to get a signoff at least from Eric who has done the most with the
> docstrings before committing. Comments from anyone else are also
> welcome of course. Darren, I think his latest approach satisfies your
> requests, but I made the comment I would prefer some of the very
> common combinations rolled up into single line decorators.
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 left out the dedentation for now, and it is untested. This can cover
lots of ground, I think it can be chained on itself:
@with_doc('append me', prepend='prepend me as well')
@with_doc(other_method)
@with_doc('prepend me %(prepend)s')
If it is not possible, or possible but messy because of dedentation or
other reasons, to pack everything into a single high-level decorator,
then maybe there should be a few like:
inherit_doc(fun) overwrite or prepend with fun's docstring
insert_doc(*args, **kwargs) interpolate
append_doc(*args)
but since these are high-level decorators, chaining decorators would
result in repeated calls to dedent.
Darren
------------------------------------------------------------------------------
Let Crystal Reports handle the reporting - Free Crystal Reports 2008 30-Day
trial. Simplify your report design, integration and deployment - and focus on
what you do best, core application coding. Discover what's new with
Crystal Reports now. http://p.sf.net/sfu/bobj-july
_______________________________________________
Matplotlib-devel mailing list
Matplotlib-devel@lists.sourceforge.net
https://lists.sourceforge.net/lists/listinfo/matplotlib-devel
