"Michael T. Richter" wrote:
>
> At 05:54 PM 9/8/99 , Andy Gill wrote:
> >I've been playing will possible formats of such documentation.
> >Have a look at http://www.cse.ogi.edu/~andy/gooddoc.htm
> >for what I'm currently thinking of.
>
> This is what I would classify as "reasonable documentation" based upon my
> current level of Haskell expertise (vanishingly small). It clearly and
> succinctly illustrates what unzip does and provides clear and simple
> examples, including its use with other features of the library and
> language. (I assume that if I knew more about infinite lists, lazy
> evaluation and the take function I'd be even more impressed.:-)
>
> >What sort of fields would be useful in a Haskeldoc program?
>
> I don't know Javadoc very well, so I don't know how to answer this. What
> fields do you have right now?
>
> And, of course, Haskelldoc will only be of use if people actually document
> their code. I know that I comment obsessively by my colleagues' standards
> here and I'm still uncomfortable with the level of documentation I provide
> in my source.... :-)
>
> BTW, what is Happy?
Hi Michael,
Happy is YACC for Haskell. Have a look at:
http://www.dcs.gla.ac.uk/fp/software/happy/
Comments are mandatory in some segments of
the software industry :-) Its been shown that
comments actually do save time (read money) for large projects.
The sort of fields I'm thinking of are:
Specification:
Sometimes the implementation rewrites some functions
to make them faster, but the original def. is clearer,
so might remain as part documentation.
Reductions:
An example worked through, line by line,
so that the operational semantics of the function become clear.
unzip [(1,2),(3,4),(5,6)]
{ by syntactical sugar }
unzip ((1,2):(3,4):(5,6):[])
{ by def. of unzip }
foldr (\(a,b) ~(as,bs) -> (a:as, b:bs)) ([], [])
((1,2):(3,4):(5,6):[])
{ by rule 1 of foldr }
(\(a,b) ~(as,bs) -> (a:as, b:bs))
(1,2)
(foldr (\(a,b) ~(as,bs) -> (a:as, b:bs)) ([], [])
((3,4):(5,6):[]))
{ by beta-reduction }
let
(as,bs) = foldr (\(a,b) ~(as,bs) -> (a:as, b:bs)) ([], [])
((3,4):(5,6):[])
in
(1:as,2:bs)
Axioms and Rules:
Algebraic properties of the definition.
Andy
