Re: [Caml-list] Re: [Caml-announce] OCamldoc

[Sven <luther@dpt-info.u-strasbg.fr>]

On Wed, Oct 10, 2001 at 08:45:04PM +0200, Maxence Guesdon wrote:
> 
> > 
> >      (** comment for f *)
> >      val f : t
> > 
> >      val f : t   (** comment for f *)
> > 
> >      val f : t
> >         (** comment for f *)
> > 
> > without the need for any funny markers.
> A simpler way is : 
> if no blank line separates the comment and the element, then they're associated. 
> What's the need for indentation ?
> BTW, I still don't buy the possibility to put comments after AND before.

This is becomming silly, ...

what is really happening here, is that so that we don't need to remmeber many
strange stuff, we are trying to agree on a common indentation solution, while
supposing that just because you don't write code in a certain way, nobody
will.

What is so difficult in remembering (*< comment **), (*> comment **) and (**
comment **) ? We are not speaking about many different comment headers, but
just three (or even two if we use (*< and (** only). What is so difficult
about it ? 

Most people will be used to be able to use any kind of space as they see fit
in their code, and will most assuredly find it much more easy to understand
something as intuitive as (**, (*< and (*> than some strange indenting stuff,
that maybe will not even be handled in the same way by all editors.

Suppose you have an editor which uses tab as 4 spaces, and you have :

    (** xxx **) (4 space used)
    val f : t (a 4 space tab being used).

Then the documentation tool, which see tabs as 8 space, or maybe 2, or
whatever will be confused, and the user will never understand it.

So, please, while trying to make the things as easy as possible _for you_,
don't make things more difficult for everyone else.

That said, it is not i who will have to respond to all the complaints of users
not understanding what is going on, so ...

Friendly,

Sven Luther
-------------------
Bug reports: http://caml.inria.fr/bin/caml-bugs  FAQ: http://caml.inria.fr/FAQ/
To unsubscribe, mail caml-list-request@inria.fr  Archives: http://caml.inria.fr