[ meta-note: can we start splitting up the discussion into separate topics, and use different subject lines for each? I'm finding it hard to keep track of a dicussion that is presented breadth-first. ] Henrik says:
1. I agree with Malcolm and Jan that the documentation conventions need to be lightweight. (I too dislike literate programming, except possibly when the aim is to write a paper or a book.)
However, I think that relying solely on positional cues might be too constraining and (in te long run) inflexible. So personally, I think HDOc/JavaDoc-like tags is a good compromise.
I've been mildly concerned about the lean towards to positional cues myself, mainly because of the constraining nature. I'm a strong believer of "mechanism not policy", but I'm aware that all too often this is a cop-out from tackling the hard problem of policy. However in this case I think we should try to separate the two at least. My vote goes to a combination of tags and mild positional cues: eg. a specially-marked comment before a type signature might be understood as documentation. I don't particularly care whether the convention is {--- -} or {-# DOC #-} (with a slight preference for the latter, because it is consistent with existing conventions). Cheers, Simon