Jan Sibinki writes:
> Am I missing something here? I thought that the Haskell Report
> does not the comments semantics.
> They are the free floating entities, and can be put anywhere
> as it pleases a module developer. And we can have many possible
> types of comments describing: module, datatype, class, function,
> etc.
> Add to it some important decorations, delimiting some
> categories of functions, and we are in a complete mess.
>
> Granted the variety of styles used, how on earth even the
> cleverest parser can figure it out? Typical parsers (I am not
> talking here about HDoc) do not care because they skip the
> comments anyway but it is not the case for the documentation
> extractors.
Sorry for not being clear about this. You're right in that trying to
understand arbitrary comments in Haskell source isn't workable. The
documentation annotations must be in a special format that the
documentation tool can understand.
eg. HDoc's {--- .. -} style comments. I had in mind using Haskell's
pragma convention, like this:
{-# DOC f
<desc><id>f</id> turns people into frogs</desc>
<arg><id>x</id> A <type>Person</type></arg>
<ret>A <type>Frog</type></ret>
#-}
f :: Person -> Frog
f x = ...
with similar annotations for classes, instances, datatypes, newtypes
etc. There's no requirement that the documentation appears directly
before the source code for the function; since it contains the
identifier of the entity being documented, it can be placed anywhere
(even in a different file).
The markup format for the documentation is of course up for discussion.
XML seems plausible but verbose.
If I understand correctly, I think you were proposing a two stage
process to get the documentation (similar to the Eiffel approach?):
Haskell source --> interface ---> on-line documentation
`--> printed documentation
.....
Why not do it in one?
Haskell source ---> on-line documentation
`--> printed documentation
....
Cheers,
Simon
