[Haskell-cafe] On documentation

[Alexander Solla]

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

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...
URL: http://www.haskell.org/pipermail/haskell-cafe/attachments/20100721/0f6fd379/attachment.html