[SciPy-dev] ndimage - docfiller and output_type

[Ralf Gommers]

On Wed, Oct 28, 2009 at 10:00 PM, <josef.pktd at gmail.com> wrote:

> On Wed, Oct 28, 2009 at 4:16 PM, Ralf Gommers
> <ralf.gommers at googlemail.com> wrote:
>
> I like your initially proposed solution, because it allows both ways,
> either
> full generic template (for distributions that nobody looks at), or
> following
> the maxwell pattern for the distributions, where someone would want to
> add individualized information.
>
> One other advantage of the generic docstring is that it is easy to create
> new
> classes outside of scipy by subclassing rv_continuous and have the
> docstring
> generated the same way as distribution in scipy.
>

Ah, I had not considered that. I will make sure not to break anything for
subclasses that do not have their own docstring. So will keep name,
longname, and extradoc.

>
> But even having your basic template is not really a problem, it's mainly
> the numpy docstring standard and the template is not something we would
> have to edit often.
> (It would still double the lines of code for many distributions).
>

It wouldn't. The simplest classes are now 18-20 lines. I can probably keep
it at the same length, and definitely below 25 lines.

>
> I still like to keep name and (maybe) longname since they are used in
> programs, if I remember correctly.
>

Sure, let's keep name. longname is not an attribute so can not be used
anywhere.


> Personally, I like extradoc, that's the only really interesting information
> about a distribution that I look at (besides dist.a and dist.b and
> dist.shape.)
> and I don't have to scroll through the boiler plate docstring to read it.
>

I'll keep it working the same, but really it should not be used. The info in
it ends up in the wrong place.

>
> (In general, I think the class should get the default constructor
> information
> in the __init__ method instead of in the instantiation.)
>

Not sure what you mean, but for normal classes in __init__ is no better than
in the class docstring. For the stats.distributions case, the instances
should not have the __init__ parameters visible at all, since they can not
be instantiated anymore.


One more thought: rv_continuous and rv_discrete should really have their own
docstrings as well. Something like
"""A generic continuous random variable class meant for subclassing.

These are my methods, and here is how you extend/override them: xxx

Parameters: xxx

Notes: more info on how to subclass, how to create a docstring, xxx

Examples: an example subclass
"""

Cheers,
Ralf
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.python.org/pipermail/scipy-dev/attachments/20091029/53bf3ef2/attachment.html>