On Wed, 31 Jan 2001, Simon Marlow wrote:
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).
That means that classes and instances (and their functions) have to be distinguished by giving the complete type of the class / instance declaration, right? E.g. class X a b where f :: a -> b instance X Person Frog where f x = ... How do we avoid that the tool confuses the two version of "f" ? An obvious way would be {-# DOC f INSTANCE X Person Frog ... #-} {-# DOC f CLASS X ... #-} (HDoc required similar "help" in early versions, but I changed that in favour of considering positional information to reduce the redundancy required in the annotations.) I guess additional annotations are an unavoidable drawback when not relying on positional information. On the other hand, being able to put the documentation in different files may be a big advantage. So, should we allow both variants? I.e. use positional information when the pragma happens to be next to a class/instance declaration (or a function therein) and rely on extra information (like "CLASS X") in the other case?
The markup format for the documentation is of course up for discussion. XML seems plausible but verbose.
As flexibility should be a priority here (we want to produce many different output formats, right?), I think XML is verbose, but not too verbose. I don't see an alternative format which is significantly less verbose. And, there's HaXml which could do a good job at processing the documentation (I haven't had a very close look at HaXml, yet). Regards, Armin