On Thu, 9 Sep 1999, S. Alexander Jacobson wrote:
> On Wed, 8 Sep 1999, Andy Gill wrote:
> >
> > Literate Haskell is simply a way of including comments.
> > Javadoc attaches meaning to stylized comments,
> > such that the tool can produce annotated indexes.
> >
> > The two concepts are orthogonal.
>
> They are only sort of orthogonal. Another approach that combines
> literate Haskell, with the javadoc thing you are talking about is to
> define an XML schema for representing Haskell code and comments.
Not a bad idea, but I'll bet that some people will object to anything
that might force them to bang out Haskell in XML files. :-)
> You can then make arbitrarily interesting transformations of source +
> comments using either HaXML or XSL. (applying XSL to this system
> gives you a programmable pre-processing, documentation, and
> packaging/instalation system for free!)
Well, once you have XML input, which isn't necessarily totally free.
But in this case you could probably get people to give you "structured
comments" that could be readily parsed into XML
> <Haskell>
> <function>
> <description>this function keeps your pants up</description>
> <keywords>
> <keywork>catamorphism</keyword>
> <keyword>blah</keyword>
> <spec>x=y</spec>
> <impl>fun x y=zip x y
> </impl>
> </function>
[you forgot the </Haskell> :-)]
-- function: fun
-- description: this function keeps your pants up
-- and is the best thing sinced sliced bread
-- keywords: catamorphism, blah
-- spec: x=y (whatever this is...)
fun :: [a] -> [b] -> [(a,b)]
fun x y = zip x y
> I don't know how you handle > and < sanely within the source,
> but using XML as the format for editing Haskell source means that you
> can use an XML editor/outliner to organize and browse which in some
> cases, can be really helpful...
I'm dubious that it's worth the effort. People already complain about
ghc and hugs error messages; I'd bet they would kill you if the code
they were developing wouldn't pass some XML validator as well. But
your hs2xml filter could (quite reasonably) complain about things that
make it hard to convert your code to XML.
Meanwhile, the answer to handling > and friends is to define your XML
schema for haskell implementation code to act more or less like
<pre></pre>, since you also need to preserve whitespace.
Another trivial (but surprisingly effective) idea to deal with getting
documentation information about functions is the one used by Matlab:
the first comment block is just grabbed as the documentation for the
function, and is indeed what "help blah" would spit back for blah.
No, it's probably not a solution any self-respecting CS person would
endorse, but people actually admire matlab's help system in practice, and
they do have something of an installed base...
jking
