[Haskell-cafe] On documentation
ajs at 2piix.com
Wed Jul 21 13:27:54 EDT 2010
On Jul 20, 2010, at 10:28 PM, Richard O'Keefe wrote:
> What I don't see is "HOW DO I USE THIS STUFF?"
I think tutorials are the best way to do that (i.e., example normal
forms for the computations the library intends to expose). Perl's
package archive (the cpan) traditionally uses a "Synopsis" section
that exposes "representative" functions at each layer/step: http://search.cpan.org/~lds/GD-2.45/GD.pm
After all, the source is always structured in more-or-less the same
way. Fragments of text with opaque -- unless/until you understand
them -- combinators "join" two distinct concepts/types into
functions. A chain of functions (potentially at various levels of
abstraction) is a computation. You "use" these things by finding a
chain of types (Start -> A), (A -> B), (B -> C), ... (N -> Goal) and
composing, filling in additional details as necessary. Building that
chain means doing depth first searches on a tree/graph of
possibilities, and usually isn't so much fun. The library developer
is in the best position to do exactly that, having already done it
while constructing the library.
-------------- next part --------------
An HTML attachment was scrubbed...
More information about the Haskell-Cafe