On Thu, Aug 13, 2009 at 11:46 AM, John Hunter<jdh2...@gmail.com> wrote:
> 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.
It suggest hashing out the basic approach and interface on the list
before applying it throughout the library.
Darren
--
"In our description of nature, the purpose is not to disclose the real
essence of the phenomena but only to track down, so far as it is
possible, relations between the manifold aspects of our experience" -
Niels Bohr
"It is a bad habit of physicists to take their most successful
abstractions to be real properties of our world." - N. David Mermin
"Once we have granted that any physical theory is essentially only a
model for the world of experience, we must renounce all hope of
finding anything like the correct theory ... simply because the
totality of experience is never accessible to us." - Hugh Everett III
------------------------------------------------------------------------------
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
