[SciPy-User] Flaws in fmin_cobyla
Thu Sep 27 15:27:22 CDT 2012
Robaula <email@example.com> wrote:
> However, I think there other, and more important issues here, namely,
> "How should the new 'minimize' interfaces be documented? How should
> existing documentation for the "old" interfaces be changed in light of
> the new 'minimize' approach? How to bring the two of them more nearly
> into alignment? Are changes to the documentation standards advisable to
> facilitate this?" Sure, "minimize's" docstring is an excellent start,
> tho I do see a couple areas where a little more explanation and/or some
> examples would be helpful. Among other things, I think it would be a lot
> better to just come out and tell folks what options are available for
> each of the various "methods", rather than telling them the code
> sequence to use to view them. Certainly the cobyla options for
> 'minimize' differ noticeably from those for the fmin_cobyla
> approach. For example, using fmin_cobyla ignores disp and iprint and
> never returns 'Results', while using 'minimize' has no iprint option,
> ignores the disp option, a nd always returns 'Results'.
> I'd welcome good ideas on how best to document the new 'minimize'
> interface, and how best to coordinate that with the "old style" method
> documentation. I'm not looking for ideas that are merely the
> programmer's personal reminders--the current documentation is just fine
> for that! Instead, I'm looking for documentation suitable for use by
> folks who might be described as: first year grad students just slightly
> familiar with Python who have a one week deadline to solve their problem
> and desperately need _very_ clear, unambiguous, and detailed
> instructions on exactly how to proceed. Try to remember _your_ first
> year grad experiences!!
A couple of things to remember about doc writing.
First, we developed the current docstring standard mainly with numpy in
mind. NumPy's structure is a lot flatter than SciPy's, and we
recognized that some additional kinds of doc pages might (or might not)
be needed for it. The Matplotlib folks made some adjustments (with our
blessing, not that they needed it) to allow the central documentation of
large sets of parameters shared by many functions (e.g., for line
thickness, color, style, etc.), something that doesn't happen in NumPy.
So, if SciPy needs something special because of its structure that isn't
covered in the standard, please bring it up on the scipy-dev mailing
list, where such discussions occur.
Rather than being a large, flat collection of loosely related and mostly
non-interacting functions, most/all of SciPy is arranged in deep modules
with lots of underlying structure and shared concepts. It does not make
sense to document such structures only on the pages of a few functions,
nor on the page of every function. Rather, you want to push that up to
the module level, and you can augment that with topical doc pages that
hang off the module, as long as they are referenced from the module doc
and those of any functions affected. That way, the doc of each function
only contains what's special to that function, and refers to the module
doc for the overview and more info.
...and all THAT said, remember that this is REFERENCE documentation. It
should talk about how the package is set up and how to get things done
in it. It needs to give examples that distinguish cases from one
another and to assist with basic use. However, exercises, descriptions
of what this area of math is for, philosophy, and extended examples
involving much more than the minimum complexity to make a point belong
in a tutorial dcoument, not a reference document. The reference docs
are not the place to get a math education. Actually, the tutorial docs
are not the best place for that, either, though they do sometimes play
that role. Rather, a good doc writer will identify several good, FREE,
online sources, often including a Wikipedia article (but READ the
article, they're not uniformly good or correct), as well as some
WIDELY-USED textbook sections, and put those in the references section
of the docs.
More information about the SciPy-User