Positional cues or not

[Manuel M. T. Chakravarty]

Henrik Nilsson <nilsson@cs.yale.edu> wrote,

> I'm not too worried about noise in this case: noise is always something
> relative, and I'd expect that the syntactic overhead of the marking
> will not be significant in comparison to the average size of
> documentation comments.
> 
> Regarding the marking conventions, I agree with Simon Marlow that it
> would be nice if the conventions are sufficiently simple so that the
> lexer easily can identify them.
> 
> It would also be nice if both end-of-line comments and brace comments
> could be used for documentation purposes, since people clearly have
> different preferences. This suggets a convention which is similar for
> the two cases.
> 
> One proposal was to allow both something like
> 
>     {---
>     -}
> 
> and
> 
>     -- --
>     --
>     ...
>     --

I am with you up to this point, as it makes lexing much
simpler.  This way, the lexer knows that it is handling
documentation without the need for contextual information. 

I agree with Marcin that it would be sufficient to use
end-of-line comments for documentation, but on the other
hand, I also accept your point about having one thing less
to argue if we just allow both styles (seems to be a small
enough price for a simplification of the decision process).

> This is OK, but maybe a little too subtle. E.g. one might be forgiven
> for wondering why not writing ---- or {- --.
> 
> On the other hand, generalizing Simon's tagged proposal seems to
> work well:
> 
>     {- @DOC
>     ...
>     -}
> 
> and
> 
>     -- @DOC
>     --
>     ..
>     --
> 
> where I took the liberty to add a @ in front of DOC (which might be
> a suitable convention for all special tags).

However, I don't agree with this anymore.  The argument
above - for having tags at all - was one of simplifying the
lexer.  Now, suddenly, you come with an argument about
subtlety, which certainly cannot be anything the lexer cares
about.  And as far as humans go, I would prefer to drop the
tags altogether rather than making them more visible.

Remember, the main tool in which code is looked at is an
ASCII text editor.  We have to optimise the notation for
that and in a text editor I don't care what is documentation
and what not, because *all* comments are documentation.
Moreover, Haskell's syntactic design follows the principle
of minimality - I don't think, it would be wise to diverge
from that for the documentation standard.

Just to reenforce the point about how annoying tags are in a
a text editor.  How am I supposed to format (in ASCII) my
documentation?  Like this

  -- --
  -- A cool function that does wonderful things and all of
  -- them automatically
  --
  foo :: Some -> cool -> type

Looks ugly.  So how about

  -- -- A cool function that does wonderful things and all of
  -- them automatically
  --
  foo :: Some -> cool -> type

Doesn't look too bad, but is very annoying to use in Emacs
filladapt mode.  I don't know about you, but when I write
comments[1], I don' want to do all the line breaks and
paragraph formatting manually.  Emacs is clever enough that
it can do automatic paragraph formatting within code
comments.  However, the second of the above styles kills its
standard algorithm.  When I press M-q (=
fill-paragraph-or-region) on the above comment, I get

  -- -- A cool function that does wonderful things and all
  -- -- of
  -- them automatically
  --
  foo :: Some -> cool -> type

which is certainly not what I want.

Summary: Any kinds of tags that interfere with the use and
formatting of comments in a standard text editor are BAD.
Anby kind of tags that are visually imposing are ugly.

Cheers,
Manuel

PS: Looking at public Haskell code in general, it seems not
    many Haskell programmers except me comment their
    programs anyway...