[SciPy-dev] ndimage - docfiller and output_type

Ralf Gommers ralf.gommers@googlemail....
Mon Nov 16 10:50:49 CST 2009

Thanks for the review Josef.

On Mon, Nov 16, 2009 at 3:52 AM, <josef.pktd@gmail.com> wrote:

> Thanks, I took your version from github. Since there are many changes,
> including cosmetic, I didn't go over all of them. I compared several
> docstrings of the old and the new version, and overall it seems to work
> very well.
> The main mistake currently is that the generic docstring for discrete is
> the same as the one for the continuous distributions, e.g.
> print stats.poisson.__doc__
> discrete distributions don't have a scale argument, and don't have a pdf
> method, instead of pdf, discrete distributions have a pmf probability mass
> function.


> Second, the generic class docstrings are pretty empty, e.g. they don't have
> the list of methods.
> print stats.distributions.rv_discrete.__doc__
> print stats.distributions.rv_continuous.__doc__
> What is missing is mainly info on how to subclass those two classes. I was
hoping you would fill in the blanks there since you know much more about how
this works than I do.

I do not think simply listing all methods is helpful, and that is also
explicitly discouraged in the doc standard.

> taste questions:
> I don't think I like the formulas in the methods, e.g. print
> stats.wald.__doc__
> I think, formulas from the extradocs should go into a notes section.

That does look a little better, done.

> I would also prefer to keep extradoc for now, even if it is not used
> anymore for the docstrings, just because I'm very used to using it. We
> can drop them later once the new system is fully working.

Sure, done.

> Given that there is more flexibility with the new system, I would
> prefer to put the extradoc information into a notes section instead of
> tucking them on at the end in the default template, if possible.
> Possible and done, looks much better now.

> Why did you special case before and after pdf?

Because the typical extradoc contains only info on the pdf. That info now
goes into Notes, so I removed before_pdf and after_pdf, and added
before_notes instead.

> Also, I think it would be better making the framework changes separate
> from any changes to the content, e.g rv_continuous, rv_discrete.

I'm not 100% sure what you mean here.

If everything works, we can edit and review changes to the content in the
> doc editor.

Yes, that would be ideal. It won't work just yet, but the next step is
indeed to get the doc editor to handle this intelligently.

> Sorry for the delay in the review, I've been busy and I have problems
> keeping up with the C changes in numpy and scipy.

No problem. I've had a few problems compiling things as well.

> (I only commented on the parts I didn't like so much, because the rest
> is a good improvement.)
I updated both the patch in ticket 1055 and the code on github. If you're
happy with the changes, can you please commit them?

-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://mail.scipy.org/pipermail/scipy-dev/attachments/20091116/748b8390/attachment.html 

More information about the Scipy-dev mailing list