Positional cues or not

[Simon Marlow]

[ 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