Re: Incomplete docs

["E. Robert Tisdale" <edwin at netwood dot net>]

G. Jungman

> 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. 

What are you documenting?
The Application Programmers' Interface (API)?
Or your particular implementation of the API?

Any feature of the implementation that you describe
as part of the API is an implicit contract between you,
the GSL library developer, and GSL application programmers.
You won't be able to change any feature of your implementation
that you describe as part of the API
without breaking some application that depends upon it.

Your description of the API
should be at the highest, most abstract level possible.
Don't say anything about the implementation
that you might wish to change at some time in the future.
Your description of the implementation
should be kept separate from your description of the API --
preferably in another document.