On Thu, Aug 13, 2009 at 9:12 AM, Darren Dale<dsdal...@gmail.com> wrote:
I don't think Jason is on the dev list, so I am CC-ing him. Please
make sure he is CC-d on all other conversations in this thread.
> 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.
Another thing to consider while cleaning this up is to not just put
the artist props into the kwdocd, but *anything* that needs
interpolating. So we could have one docstring.interpd into which all
keys 'Line2D', 'Patch', 'AvailableArrowstyles', 'PSD', 'scale_docs',
etc... Right now we have a hodge-podge of doc interpolation strings,
and it might make sense to simplify this by putting them all into a
single interp dict that can be used anywhere in mpl.
Jason, I hope we don't exhaust you with these suggestions -- this will
be a very nice cleanup and a big help for people using mpl in
installers like py2exe which strip out docs with the optimization
flags. But as Darren said we need to get this right and keep the
interface as simple as possible while preserving all the current
functionality. Thanks for all your efforts.
JDH
------------------------------------------------------------------------------
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
