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