malcolm-hs@cs.york.ac.uk wrote,
I have another big requirement. The source code must remain readable as source code. I absolutely loathe so-called "literate programming" style, because it breaks this rule horribly. From my point of view, any new documentation standard must be as non-intrusive as possible. This almost immediately rules out XML-style tags I'm afraid. Other (less heavy) lexical conventions might be OK though, provided there are only a small number of them to be learnt.
I am 100% with you here. If a documentation standard makes the code in my editor only the slightest bit less readable, I won't use it. This, btw, also means that the tool has to understand -- bla bla bla -- blub blub blub kind of comments and not only something like {- bla bla bla blub blub blub -} Nested comments don't go well with syntax highlighting.
I am intrigued by the use of positional cues (e.g. a comment just before or just after a type signature) as a clever way of associating documentation with code, whilst avoiding extra syntax.
I like that, too.
For those who have not yet looked at Armin's HDoc, can I encourage you to do so, as a concrete example of how some of these ideas have been put into practice. He develops a "special" kind of comment, introduced by {--- rather than {-, and has some small lexical conventions that help to generate nice hyperlinked HTML.
Does HDoc also grok ---- for a comment block rather than --? Maybe it must actually be something like -- -- to make sure ---- is not read as one token by a Haskell compiler (by longest match rule). Cheers, Manuel