This is the mail archive of the gsl-discuss@sources.redhat.com mailing list for the GSL project.


Index Nav: [Date Index] [Subject Index] [Author Index] [Thread Index]
Message Nav: [Date Prev] [Date Next] [Thread Prev] [Thread Next]

Re: Incomplete docs


Jake Kesinger wrote:
> 
> I'm a brand new user of GSL (where was this when I *really* needed it
> three years ago? :-)  and I notices that the docs could use a little bit
> of sprucing up, especially with some of the special functions (i.e.
> Gamma(z), and Legendre polynomials).
> 
> I *am* volunteering to try and add a little verbiage to the docs, if
> the maintainers are interested.  Please let me know.

Great. That would be most welcome. Anything would be appreciated there.
If you do anything with this, just go ahead and send the
files directly to the mailing list, and I will merge them.

My philospohy for what it's worth:
  o We're not writing a book on numerical analysis,
    so there is no need for lots of extra discussion.
  o Examples should illustrate how to use the
    interfaces and not illustrate more general points.
  o The docs for each special function should say
    what the mathematical definition is, what
    the restrictions of the implementation are
    (if an argument is supposed to be positive, etc),
    and what the possible exceptions (return codes)
    are.

The last point about error codes is a sticky one,
because it is hard to keep the docs in synch with
the implementation. Even I don't know for sure what
codes can propagate back up through some of those
functions. So we can't hope for too much there.

Anyway, I always try to put those bits of important
information in the header files; otherwise I forget
myself what something is doing.

If you're not sure about some things, you can ask
or just leave it out. 


Thanks.

-- 
G. Jungman

Index Nav: [Date Index] [Subject Index] [Author Index] [Thread Index]
Message Nav: [Date Prev] [Date Next] [Thread Prev] [Thread Next]