On Wed, 8 Sep 1999, Andy Gill 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 looks real nice. As someone else on the list pointed out it would be
nice to have this kind of documentation on the module level also. My
experience from Java tells me that this could be extremely useful. Also,
documentations for types and classes is also a must IMO.
Maybe the definition of a function should be left out from the
documentation, at least by default. Javadoc has a number of options so
that one can choose how much information the documentation should contain.
If we have a good specification and a set of axioms and rules, that's all
we need. Taking javadoc as an example again, imagine how it would look if
it included the definition of every function (yes, I know it's not really
comparable :-).
> > >What sort of fields would be useful in a Haskeldoc program?
> >
The documentation of a type should contain class-instances.
The fixity of a function, if it's declared, should be documented.
> 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)
>
This strikes me as odd. How can you define the operational semantics of a
function when Haskell does not have an operational semantics?
> Axioms and Rules:
>
> Algebraic properties of the definition.
>
/Josef
----------------------------------------------------------
|Josef Svenningsson|http://www.dtek.chalmers.se/~d95josef|
|Rubingatan 39 | email: [EMAIL PROTECTED] |
|421 62 Göteborg | tel: 031-7090774 |
----------------------------------------------------------
What is a magician but a practising theorist?
-- Obi-Wan Kenobi
