Ed Leafe wrote:
> On Mar 16, 2007, at 8:19 PM, Paul McNett wrote:
>
>>> If you are repeating the parameters for one of these methods, why
>>> not repeat them for all?
>> Say again?
>
> The parameters are documented in the docstring for the mixin class.
> Why not repeat them for each of the methods? This way you can have
> them documented in each method as well as the class.
Ok, go real slow, I've had a couple glasses of wine after a hectic week.
Oh, wait a sec. I just realized that you already had the parameters
documented at the class level... is that what you meant? Shoot, what a
duplicated waste of effort I wouldn't have embarked on had I realized
that you already did that.
I was doing some sizer stuff this afternoon and I realized I didn't have
a clear idea what the various border settings did, so I went to the api
docs and only found:
"""
append(self, item, layout='normal', proportion=0, alignment=None,
hAlign='left', vAlign='top', border=None, borderSides=None,
borderFlags=None):
Adds the passed object to the end of the last item controlled by the sizer.
"""
There wasn't any doc associated with dSizer at the top of the document,
but I see now that you have the docstring defined in dSizerMixin. I
suppose I have a problem with the api doc where it only pulls the class
docstring, not inherited from superclasses.
When I went to edit the class, I just instinctively went to the method
in question and didn't look at the class definition.
Anyway, I think the class docstring should explain what the class does
in a high-level fashion, and that the method docstrings should explain
what the method does as well as what the arguments do, if it isn't obvious.
So I guess we should repeat that long docstring in append, prepend, and
insert, although copy/paste feels wrong. I think we may be able to:
doc_additions = """ blah blah"""
def append(...)
"""Adds the passed object...""" + doc_additions
...or something of that nature.
--
pkm ~ http://paulmcnett.com
_______________________________________________
Post Messages to: [email protected]
Subscription Maintenance: http://leafe.com/mailman/listinfo/dabo-dev
