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

[Patrick M Doane <patrick@watson.org>]

On Tue, 9 Oct 2001, Maxence Guesdon wrote:

> > Besides, I think it is usually more readable to put the comment after
> > the element.  Indeed, you often search for an element (by name), and
> > then read the corresponding comment.
> 
> I agree that, in .mli files for example, i prefer to have the comment 
> after the definition, but for consistency between .ml and .mli files,
> the comment-before-definition way was chosen.

Placing comments after the definition is standard O'Caml practice. It
would be a shame to lose this as most source code already follows this
convention.

I also don't understand the need for consistency between the .ml and .mli
files. The documentation effort for an implementation is a very different
task than for its interface.

I agree that this may make things more difficult, but the O'Caml community
has a long-standing tradition of compatibility with previous design
choices. Comments after definition in the .mli file is a choice that most
of us, including yourself, prefer anyways.

Patrick

-------------------
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