[Caml-announce] OCamldoc

[Caml-announce] OCamldoc

[Maxence Guesdon]

Hello

I'm pleased to announce a pre-release of OCamldoc, which i hope will 
become the "javadoc for OCaml".
http://www.maxence-g.net/tools.html

'nough said !

--
Maxence Guesdon

==================================
Bonjour,

J'ai le plaisir d'annoncer une préversion de OCamldoc, qui j'espère 
deviendra le "javadoc de OCaml".
http://www.maxence-g.net/tools.html

--
Maxence Guesdon

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

[Francois Pottier]

Hi,

> I'm pleased to announce a pre-release of OCamldoc, which i hope will 
> become the "javadoc for OCaml".

Congratulations for this very nice piece of work.

A question about comment placement: isn't it a bit inconsistent to
expect comments for record fields to be placed *after* the record,
while the opposite convention is used for object fields?

I would consider it more consistent to always require the comment to
precede the element. The purpose of the current convention concerning
record fields and data constructors seems to be to encourage people
to write comments that fit on the remainder on the line, which is bad
practice anyway.

-- 
François Pottier
Francois.Pottier@inria.fr
http://pauillac.inria.fr/~fpottier/
-------------------
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

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

[Fabrice Le Fessant]

What about adding a special keyword in ocamldoc comments to indicate
to which function the comment applies ? :) You could then get rid of
the placement limitation. Another option would be to override the
default behavior either by an option or a configuration file !

a+

- Fabrice

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

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

[Jerome Vouillon]

On Tue, Oct 09, 2001 at 08:26:48AM +0200, Francois Pottier wrote:
> I would consider it more consistent to always require the comment to
> precede the element. The purpose of the current convention concerning
> record fields and data constructors seems to be to encourage people
> to write comments that fit on the remainder on the line, which is bad
> practice anyway.

You don't have to put the comment on the same line.  You can write:
    type t =
        C1 of int
            (** constructor 1 *)
      | C2 of float
            (** constructor 2 *)

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.  So, for instance, I prefer this:
    val to_list: 'a array -> 'a list
            (* [Array.to_list a] returns the list of all the elements
               of [a]. *)
    val of_list: 'a list -> 'a array
            (* [Array.of_list l] returns a fresh array containing the
               elements of [l]. *)
    val iter: f:('a -> unit) -> 'a array -> unit
            (* [Array.iter f a] applies function [f] in turn to all
               the elements of [a].  It is equivalent to
               [f a.(0); f a.(1); ...; f a.(Array.length a - 1); ()]. *)
to this:
    (** [Array.to_list a] returns the list of all the elements of [a]. *)
    val to_list: 'a array -> 'a list
    (** [Array.of_list l] returns a fresh array containing the elements
        of [l]. *)
    val of_list: 'a list -> 'a array
    (** [Array.iter f a] applies function [f] in turn to all
        the elements of [a].  It is equivalent to
        [f a.(0); f a.(1); ...; f a.(Array.length a - 1); ()]. *)
    val iter: f:('a -> unit) -> 'a array -> unit

What about the following syntax?
- The comment is before the element:
      (** fun 1 *)
      val f : t
      (** fun 2 *)
      val g : u
- The comment is after the element:
      val f : t
        (* fun 1 **)
      val g : u
        (* fun 2 **)

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

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

[Eric C. Cooper]

Jerome Vouillon wrote:
> 
> What about the following syntax?
> - The comment is before the element:
>       (** fun 1 *)
>       val f : t
>       (** fun 2 *)
>       val g : u
> - The comment is after the element:
>       val f : t
>         (* fun 1 **)
>       val g : u
>         (* fun 2 **)

I like this -- it's an elegant solution that lets both styles coexist
naturally.

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

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

[Patrick M Doane]

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

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

[Maxence Guesdon]

Hello

> Congratulations for this very nice piece of work.
Thanks.

> A question about comment placement: isn't it a bit inconsistent to
> expect comments for record fields to be placed *after* the record,
> while the opposite convention is used for object fields?
> I would consider it more consistent to always require the comment to
> precede the element. The purpose of the current convention concerning
> record fields and data constructors seems to be to encourage people
> to write comments that fit on the remainder on the line, which is bad
> practice anyway.
I *agree* that this can be viewed as inconsistency, but i think comments 
for record fields and data constructors are usually quite short, since 
they are a complement to the type comment. Moreover, do you prefer

type t =
   (** constructor 1 *)
   C1 of int
   (** constructor 2 *)
| C2 of float
   (** constructor 3 *)
| C3 of string

or

type t =
   C1 of int (** constructor 1 *)
| C2 of float (** constructor 2 *)
| C3 of string (** constructor 3 *)

?

i prefer the second one, which more easily gives me an overview of the 
type. But it's only a matter of taste ;-)

Anyway, thanks for our interest

--
Maxence



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

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

[Maxence Guesdon]

> 
> 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.  So, for instance, I prefer this:
>     val to_list: 'a array -> 'a list
>             (* [Array.to_list a] returns the list of all the elements
>                of [a]. *)
>     val of_list: 'a list -> 'a array
>             (* [Array.of_list l] returns a fresh array containing the
>                elements of [l]. *)
>     val iter: f:('a -> unit) -> 'a array -> unit
>             (* [Array.iter f a] applies function [f] in turn to all
>                the elements of [a].  It is equivalent to
>                [f a.(0); f a.(1); ...; f a.(Array.length a - 1); ()]. *)
> to this:
>     (** [Array.to_list a] returns the list of all the elements of [a]. *)
>     val to_list: 'a array -> 'a list
>     (** [Array.of_list l] returns a fresh array containing the elements
>         of [l]. *)
>     val of_list: 'a list -> 'a array
>     (** [Array.iter f a] applies function [f] in turn to all
>         the elements of [a].  It is equivalent to
>         [f a.(0); f a.(1); ...; f a.(Array.length a - 1); ()]. *)
>     val iter: f:('a -> unit) -> 'a array -> unit

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.


> What about the following syntax?
> - The comment is before the element:
>       (** fun 1 *)
>       val f : t
>       (** fun 2 *)
>       val g : u
> - The comment is after the element:
>       val f : t
>         (* fun 1 **)
>       val g : u
>         (* fun 2 **)

I must admit i'd rather keep very simple placement rules.

--
Maxence



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

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

[rbw3]

doxygen (a C++ doc tool, see http://www.stack.nl/~dimitri/doxygen/ ) adds
the '<' only for comments following, keeping the normal notation for
preceding ones, as follows. I just thought I'd mention it to give more
ideas.

(** My magical function *)
let magical = function
  | CaseA -> 0 (*< this is case 0 *)
  | CaseB -> 1 (*< this is case 1 *)
  | CaseC -> 2 (*< this is case 2 *)
  | _ -> raise Not_found (*< Too bad, so sad *)


--Brock


On Tue, 9 Oct 2001, Maxence Guesdon wrote:
| > What about the following syntax?
| > - The comment is before the element:
| >       (** fun 1 *)
| >       val f : t
| >       (** fun 2 *)
| >       val g : u
| > - The comment is after the element:
| >       val f : t
| >         (* fun 1 **)
| >       val g : u
| >         (* fun 2 **)
|
| I must admit i'd rather keep very simple placement rules.
|
| --
| Maxence
-------------------
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

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

[Francois Pottier]

> doxygen (a C++ doc tool, see http://www.stack.nl/~dimitri/doxygen/ ) adds
> the '<' only for comments following, keeping the normal notation for
> preceding ones, as follows. I just thought I'd mention it to give more
> ideas.
> 
> (** My magical function *)
> let magical = function
>   | CaseA -> 0 (*< this is case 0 *)
>   | CaseB -> 1 (*< this is case 1 *)
>   | CaseC -> 2 (*< this is case 2 *)
>   | _ -> raise Not_found (*< Too bad, so sad *)

Looks nice to me.

-- 
François Pottier
Francois.Pottier@inria.fr
http://pauillac.inria.fr/~fpottier/
-------------------
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

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

[rbw3]

[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #1: Type: TEXT/PLAIN; charset=X-UNKNOWN, Size: 1370 bytes --]


hm. I just noticed that I actually made a small mistake in my example. It
should be:

(** My magical function *)
let magical = function
  | CaseA -> 0 (**< this is case 0 *)
  | CaseB -> 1 (**< this is case 1 *)
  | CaseC -> 2 (**< this is case 2 *)
  | _ -> raise Not_found (**< Too bad, so sad *)


with the added '*' in the after-comments. Funnily enough I like my mistaken
one better :)

--Brock

PS.
  Though I've seen this reply to me email, I haven't seen my original
  email yet. Just thought I'd share the speed of processing on the list
  from my vantage point.

On Wed, 10 Oct 2001, Francois Pottier wrote:

|
| > doxygen (a C++ doc tool, see http://www.stack.nl/~dimitri/doxygen/ ) adds
| > the '<' only for comments following, keeping the normal notation for
| > preceding ones, as follows. I just thought I'd mention it to give more
| > ideas.
| >
| > (** My magical function *)
| > let magical = function
| >   | CaseA -> 0 (*< this is case 0 *)
| >   | CaseB -> 1 (*< this is case 1 *)
| >   | CaseC -> 2 (*< this is case 2 *)
| >   | _ -> raise Not_found (*< Too bad, so sad *)
|
| Looks nice to me.
|
| --
| François Pottier
-------------------
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

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

[Sven]

On Tue, Oct 09, 2001 at 12:20:43PM +0200, Jerome Vouillon wrote:
> On Tue, Oct 09, 2001 at 08:26:48AM +0200, Francois Pottier wrote:
> > I would consider it more consistent to always require the comment to
> > precede the element. The purpose of the current convention concerning
> > record fields and data constructors seems to be to encourage people
> > to write comments that fit on the remainder on the line, which is bad
> > practice anyway.
> 
> You don't have to put the comment on the same line.  You can write:
>     type t =
>         C1 of int
>             (** constructor 1 *)
>       | C2 of float
>             (** constructor 2 *)
> 
> 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.  So, for instance, I prefer this:
>     val to_list: 'a array -> 'a list
>             (* [Array.to_list a] returns the list of all the elements
>                of [a]. *)
>     val of_list: 'a list -> 'a array
>             (* [Array.of_list l] returns a fresh array containing the
>                elements of [l]. *)
>     val iter: f:('a -> unit) -> 'a array -> unit
>             (* [Array.iter f a] applies function [f] in turn to all
>                the elements of [a].  It is equivalent to
>                [f a.(0); f a.(1); ...; f a.(Array.length a - 1); ()]. *)
> to this:
>     (** [Array.to_list a] returns the list of all the elements of [a]. *)
>     val to_list: 'a array -> 'a list
>     (** [Array.of_list l] returns a fresh array containing the elements
>         of [l]. *)
>     val of_list: 'a list -> 'a array
>     (** [Array.iter f a] applies function [f] in turn to all
>         the elements of [a].  It is equivalent to
>         [f a.(0); f a.(1); ...; f a.(Array.length a - 1); ()]. *)
>     val iter: f:('a -> unit) -> 'a array -> unit
> 
> What about the following syntax?
> - The comment is before the element:
>       (** fun 1 *)
>       val f : t
>       (** fun 2 *)
>       val g : u
> - The comment is after the element:
>       val f : t
>         (* fun 1 **)
>       val g : u
>         (* fun 2 **)

Huh, ...

I think this whole thing is largely a personnal preference thing (altough i
myself put commentes before, especially when the function, declaration or
whatever is large). What about a configuration option so people could choose
their mode ?

You could have a :

(*** comment before **)

or a :

(*** comment after **)

At the begining of the files, or use a command line switch ?

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

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

[Frank Atanassow]

Benjamin C. Pierce wrote (on 13-10-01 07:49 -0400):
> (I'm glad we've had
> so much discussion about it, though, because now people will think twice
> before proposing *more* funny characters to go in comments... :-)

Whoa, hold on there! You haven't heard my proposal yet:

I think we should have documentation comments of the form

  (*<r1> ... <r2>*)

where r1 and r2 are REGULAR EXPRESSIONS which match the part of the source
that the documentation applies to. This covers all the possible cases, plus
MANY MORE. Not only can you have the comment BEFORE, on THE SAME LINE and
AFTER but also IN THE MIDDLE of your code! Just think of all the possibilities
for SELF-EXPRESSION and CUSTOMIZATION. No more WORRIES or CONSTERNATION about
finding the right spot: just put it ANYWHERE.

Some people might argue against this because it is overly complicated, and you
would have to change the regular expressions if you move the comment, but THAT
IS WHAT O'REILLY BOOKS AND PROGRAMMABLE EDITORS ARE FOR!  In fact, I can
imagine a whole INDUSTRY growing out of this. Think of the BUSINESS
OPPORTUNITIES, an entire NEW MARKET. I urge you ALL to GET IN ON THE GROUND
FLOOR NOW, before you MISS OUT!!!!

[I wonder how many people's spam filters got triggered on this... <gulp!>]

Seriously though, my preferences are, in order:

  1) only (** ... *) comments preceding the code, as in Java;
  2) Benjamin's indentation-significant style
  3) Jerome's (** ... *) and (* ... **) comments

My reasoning is that 1) is best because, since this is a new feature and no
one is forced to use it, it's not unreasonable to expect people to stylize
their documentation comments according to a single, new convention which is,
anyway, familiar from Java. 2) is better than 3) for the reason Benjamin
mentioned already: if you move the comment, you have to remember to change the
asterisks, and that seems pretty error-prone to me.

Someone argued that significant indentation is a burden for source
preprocessors as they need to preserve the indentation exactly. I don't
find this so convincing since preprocessor _output_ is usually not meant for
human eyes at all, but rather for the compiler. Usually you will run CamlDoc
on the preprocessor _input_, right? A preprocessor could even just convert
all the documentation comments to regular comments if it didn't want to
produce misleading output.

-- 
Frank Atanassow, Information & Computing Sciences, Utrecht University
Padualaan 14, PO Box 80.089, 3508 TB Utrecht, Netherlands
Tel +31 (030) 253-3261 Fax +31 (030) 251-379
-------------------
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

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

[Mike Leary]

which, in any case, ought to be, IMO:

(** short comment, or longer comment **)
type t = 
    C of <insert very long multi line type here>

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

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

[Jimmie Houchin]

"Benjamin C. Pierce" wrote:
> 
> > > The worst thing wrong with this convention in Make is that \t and eight
> > > spaces look the same but mean different.  Nothing like that is being
> > > proposed here.
> >
> > I'm afraid it is. The notion of two things being at the `same indentation
> > level' is dependent on the number of spaces which \t expands into, isn't
> > it?
> 
> I see this as a minor problem.  After all, the only indentation levels
> that are likely to matter for this application are zero and nonzero!
> 
> Still, I'm not all that opposed to Jerome's suggestion -- it's a little
> heavier than the minimum, in my view, but not much.  (I'm glad we've had
> so much discussion about it, though, because now people will think twice
> before proposing *more* funny characters to go in comments... :-)

The Python community has few problems with indentation or white space
being significant. The people who have problems generally weren't
open-minded about it and generally never accepted Python and generally
don't use. There are exceptions, but there always are.

About the difference in tabs and spaces. Generally the only problem you
have is when the individual mixes the together differently. This
generally doesn't happen. If all of the dire tab and spacing issues were
common source code would look funny to everyone all the time in every
language. I believe IMHO that it is generally more consistent than that.

Regardless, if the individual who wrote the code indented/tabbed/spaced
the two lines identically with the exception of the second line being
being indented more. Then it should make little difference because the
second line is indented past the point of the first, regardless of
indentation style or tab/space expansion.

If it looks right in their editor it should parse correctly.

People generally don't tab to a place on one line and then space to the
same point on the next line. They will generally do the same thing on
both lines to reach the same point and then do something additional on
the second. That should be all that's necessary.

If someone's creative use of the editors preferences and choice of
indenting styles breaks the parsing of OCamldoc, then some education
would be what's appropriate. Regardless of which system is chosen there
will be an educational process on behalf of the users to learn the
system. I would hate to see this system not chosen simply because of
indentation.

Just thought I would throw that out there. :)
I'm not qualified in any other way. I'm just learning OCaml.
But, if I voted, I like Benjamin's version.

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

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

[Benjamin C. Pierce]

> > The worst thing wrong with this convention in Make is that \t and eight
> > spaces look the same but mean different.  Nothing like that is being
> > proposed here.  
> 
> I'm afraid it is. The notion of two things being at the `same indentation
> level' is dependent on the number of spaces which \t expands into, isn't
> it?

I see this as a minor problem.  After all, the only indentation levels
that are likely to matter for this application are zero and nonzero!

Still, I'm not all that opposed to Jerome's suggestion -- it's a little
heavier than the minimum, in my view, but not much.  (I'm glad we've had
so much discussion about it, though, because now people will think twice
before proposing *more* funny characters to go in comments... :-)

       Benjamin


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

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

[Marcin 'Qrczak' Kowalczyk]

Fri, 12 Oct 2001 11:10:25 +0200, Sven <luther@dpt-info.u-strasbg.fr> pisze:

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

The mistake is in using something other than 8 as tab size.

I don't understand complaints that tabs are so bad because different
tab sizes when mixing tabs with spaces cause confusion. The solution
is simple: use 8 only as the size.

-- 
 __("<  Marcin Kowalczyk * qrczak@knm.org.pl http://qrczak.ids.net.pl/
 \__/
  ^^                      SYGNATURA ZASTĘPCZA
QRCZAK

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

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

[Alan Schmitt]

* Francois Pottier (francois.pottier@inria.fr) wrote:
> I'll second Jérôme's suggestion for (** *) and (* **).

I'll third (or maybe fourth) it then ;-)

Alan

--
The hacker: someone who figured things out and made something cool happen.
-------------------
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

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

[Francois Pottier]

Benjamin,

> The worst thing wrong with this convention in Make is that \t and eight
> spaces look the same but mean different.  Nothing like that is being
> proposed here.  

I'm afraid it is. The notion of two things being at the `same indentation
level' is dependent on the number of spaces which \t expands into, isn't
it?

I'll second Jérôme's suggestion for (** *) and (* **).

-- 
François Pottier
Francois.Pottier@inria.fr
http://pauillac.inria.fr/~fpottier/
-------------------
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

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

[Benjamin C. Pierce]

[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #1: Type: text/plain, Size: 2417 bytes --]

OK, just one more comment on comments from me too...

> Also, I was taught to believe that relying on white space/tabulations/blanks
> for the meaning was awful backward technology (see the \t in Makefiles...).
> Why should this not apply to the ``semantics of comments''? 

The worst thing wrong with this convention in Make is that \t and eight
spaces look the same but mean different.  Nothing like that is being
proposed here.  

> Overall, I find Jérome's suggestion to use (** aaa *) and (* aaa **) to
> indicate placement visually light while it seems to providing *all* the
> flexibility that people are calling for: placement should either be before
> or after the element, but explicit.

Note that it's also a bit more error prone: if I move a comment from
after to before but forget to change its funny marker, it will get
attached to the wrong place.

More generally: there is not going to be a perfect solution to this
problem -- any solution is going to be a tradeoff between 
   - desire of people who work directly with the code to keep it readable
   - desire of documentation writers to do fancy arbitrary stuff easily
   - simplicity of implementation
   - needs of other tools like prettyprinters

All I'm saying is that I care a *lot* more about #1 than any of the
others.  

But, having expressed my opinion about it, I'll be quiet now -- the
OCamlDoc designers and implementors [*] have done a great job with what's
there already, and I'm sure that, whatever the details of the final tool
turn out to look like, it will do the job just fine.

        B

[*] I get the impression that several people at INRIA are talking about
it and Maxence is taking the lead on the detailed design and
implementation -- is that right?

-----------------------------------------------------------------------------
BENJAMIN C. PIERCE
Associate Prof., Computer & Information Science        bcpierce@cis.upenn.edu
University of Pennsylvania                                    +1 215 898-2012
200 South 33rd St.                                       Fax: +1 215 898-0587
Philadelphia, PA 19104, USA                http://www.cis.upenn.edu/~bcpierce
-----------------------------------------------------------------------------





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

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

[Markus Mottl]

On Fri, 12 Oct 2001, Sven wrote:
> 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 ?

I agree with Sven here: two or three simple annotations are hardly a
burden to remember. Using indentation for correctly associating comments
with declarations simply doesn't fit to the language, IMHO.

Just my two Euro-cents,
- Markus

-- 
Markus Mottl                                             markus@oefai.at
Austrian Research Institute
for Artificial Intelligence                  http://www.oefai.at/~markus
-------------------
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

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

[Fabrice Le Fessant]

I agree with Jerome and Didier. (** ... *) and (* ... **) is a simple
syntax, and leaves (* ... *) for personnal comments. Moreover, I like 
{tag ... } instead of <tag> ... </tag> and [ ... ] for code, because
you can still read comments without opening lynx ... 

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

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

[Sven]

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

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

[Didier Remy]

My own little comment on comments...

I also wish that the syntax of documentation should remain simple to
understand and visually light, so that the commented code can be read and
writen, directly! without yet another tool...

However, I am worried if this were to rely on indentation. I think that this
is a heavy contraint put on programmers (every one has his own style).
Moreover, this will force all automatic indentation tools (e.g. the
emacs-mode etc.) to understand the meaning of indentation *perfectly* so as
not to break them. This makes these tools very fragile.  Note that today,
these tools only change the presentation, and at worse, there produce a bad
taste indentation but never *loose* information. 

Also, I was taught to believe that relying on white space/tabulations/blanks
for the meaning was awful backward technology (see the \t in Makefiles...).
Why should this not apply to the ``semantics of comments''? 

Overall, I find Jérome's suggestion to use (** aaa *) and (* aaa **) to
indicate placement visually light while it seems to providing *all* the
flexibility that people are calling for: placement should either be before
or after the element, but explicit.

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

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

[Andreas Rossberg]

Xavier Leroy wrote:
> 
> I've been
> hacking Lex and Yacc for years, still I do not have the slightest idea
> on how to take indentation into account in a Lex/Yacc parser...

What you can do is, write a standard lexer and a (more or less, see
below) standard parser. In addition, you write a lexer wrapper that does
several things:

- calculate line/column information from the absolute character position
  for every token (e.g. by incrementally co-traversing the input),
- maintain a stack of current indentation levels,
- insert some appropriate virtual tokens on line and indentation level
changes.

The grammar implemented by the parser contains occurences of these
virtual tokens at the right places. In the approach taken by Haskell
(don't know about Python) you do not even need to think about that,
since you only insert standard tokens. And if you have a lexer that is
able to calculate lines/columns by itself, everything becomes very easy.

-- 
Andreas Rossberg, rossberg@ps.uni-sb.de

"Computer games don't affect kids; I mean if Pac Man affected us
 as kids, we would all be running around in darkened rooms, munching
 magic pills, and listening to repetitive electronic music."
 - Kristian Wilson, Nintendo Inc.
-------------------
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

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

[Daniel de Rauglaudre]

Hi,

On Fri, Oct 12, 2001 at 08:23:27AM +0200, Francois Pottier wrote:

> True, but using indentation for this purpose will make life more
> difficult for tools that must pretty-print code (such as camlp4),
> won't it?

Normally no. When Camlp4 pretty prints a comment, it takes the
identation with.

-- 
Daniel de RAUGLAUDRE
daniel.de_rauglaudre@inria.fr
http://cristal.inria.fr/~ddr/
-------------------
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

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

[Francois Pottier]

> A simpler way is : 
> if no blank line separates the comment and the element, then they're associated. 
> What's the need for indentation ?

Ah, but some people (including me) want to insert a blank line between
comment and element... (Sorry to be so picky :)

-- 
François Pottier
Francois.Pottier@inria.fr
http://pauillac.inria.fr/~fpottier/





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

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

[Francois Pottier]

On Wed, Oct 10, 2001 at 11:10:16PM +0900, Jacques Garrigue wrote:

> I think that the above rules match rather closely what most people
> write anyway. A documentation tool is based on conventions, as visual
> as possible (you want to read the comments in the source too).

True, but using indentation for this purpose will make life more
difficult for tools that must pretty-print code (such as camlp4),
won't it?

-- 
François Pottier
Francois.Pottier@inria.fr
http://pauillac.inria.fr/~fpottier/
-------------------
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

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

[Marcin 'Qrczak' Kowalczyk]

Thu, 11 Oct 2001 21:32:11 +0200, Xavier Leroy <xavier.leroy@inria.fr> pisze:

> But: languages where indentation is significant (Haskell, Occam,
> Python) have bad reputation as being 1- harder to parse (for a
> program), and 2- intolerant w.r.t. cut-and-paste or machine-generated
> code.  2- is perhaps less of a problem for documentation comments
> (they are rarely machine-generated :-), but 1- worries me.  I've been
> hacking Lex and Yacc for years, still I do not have the slightest idea
> on how to take indentation into account in a Lex/Yacc parser...

I've recently implemented a toy language with significant layout.
Conclusions:

It's easy to parse with a lexer written by hand and a parser generated
by Happy (Yacc for Haskell). What is needed (and what Happy provides):
a state threaded through both lexer and parser. The lexer converts
layout to virtual brackets of some sort and virtual semicolons.

It's easy to write a lexer by hand in a functional language. I don't
know about handling layout with Lex. Parsing is not affected by layout.

Significant layout is practical for languages with enough static
checking (either by static typing or by a redundant grammar). It's
impractical for languages where almost any sequence of tokens is
valid at compile time.

In particular it works for Haskell (both reasons) and Python
(grammar with enough amount of redundancy). It didn't work well
for my language :-)

I'm sure it would work for core OCaml, but there might be problems
with ocamldoc if errors in layout of special comments are generally
not catched and just change the meaning.

-- 
 __("<  Marcin Kowalczyk * qrczak@knm.org.pl http://qrczak.ids.net.pl/
 \__/
  ^^                      SYGNATURA ZASTĘPCZA
QRCZAK

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

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

[Xavier Leroy]

I'm catching up with this lively discussion, which echoes some of the
discussions we've had previously among the OCaml developers.  

I was among the ones who suggested Maxence to stick to a simple,
consistent convention, even if it doesn't quite match the comment
style that we've used before.  Having a convention that is simple to
explain and to implement is a big plus.  OCamldoc is just a program
after all; expecting it to "understand" various pre-existing comment
styles is unrealistic.  I'm willing to adapt my comment style accordingly
(and edit all the .mli files in the OCaml libraries...).

Since comments in .ml implementation files naturally come before the
definitions, it seemed logical to adopt the same convention for .mli
interfaces,  In particular, it often happens that we cut-and-paste
type definitions between interfaces and implementations, so the
comment style must be the same for both.

This said, Benjamin's proposal looks appealing:

> I.e., *one* kind of (not very) funny comment marker, plus using the
> indentation to decide whether the comment binds to the expression before
> or after:
> 
>       if the comment is on a line by itself, 
>       then if its indentation is the same as the following (non-comment) line
>            then it goes with the following
>            else it goes with the preceding
>       else it goes with the line it's on.

That isn't too hard to explain, and matches current practice well.

But: languages where indentation is significant (Haskell, Occam,
Python) have bad reputation as being 1- harder to parse (for a
program), and 2- intolerant w.r.t. cut-and-paste or machine-generated
code.  2- is perhaps less of a problem for documentation comments
(they are rarely machine-generated :-), but 1- worries me.  I've been
hacking Lex and Yacc for years, still I do not have the slightest idea
on how to take indentation into account in a Lex/Yacc parser...

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

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

[Florian Hars]

On Wed, Oct 10, 2001 at 03:38:27PM -0400, Benjamin C. Pierce wrote:
> On the other hand, having to insert blank lines between these would not
> bother me all that much.

Messing up blank lines is easier than messing up indentation (especially
if the tool in question considers lines containing a non-empty amount
of whitespace as non-empty: you have no chance to see how the tool
will treat a given comment that follows a line that looks empty, does
OCamldoc belong to this class?).

Yours, Florian.
-------------------
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

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

[Benjamin C. Pierce]

> One important issue here is that author A may want to escape to LaTeX and
> author B may want to escape to HTML. Are you suggesting that there
> should be only one escape language or one escape sequence that brings you
> to whatever language the author wants to use?

Why on earth would anyone want to escape to anything other than hevea?  :-)

    B
    
    

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

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

[Benjamin C. Pierce]

> A simpler way is : 
> if no blank line separates the comment and the element, then they're associated. 
> What's the need for indentation ?

I do sometimes group several small definitions together in .mli files,
like this

     (* Comment for f1 *)
     val f1 : t1
     (* Comment for f2 *)
     val f2 : t2
     (* Comment for f3 *)
     val f3 : t3

     (* Comment for g1 *)
     val g1 : t1
     (* Comment for g2 *)
     val g2 : t2

and for this the indentation convention would be useful.

On the other hand, having to insert blank lines between these would not
bother me all that much.

      B
      
-----------------------------------------------------------------------------
BENJAMIN C. PIERCE
Associate Prof., Computer & Information Science        bcpierce@cis.upenn.edu
University of Pennsylvania                                    +1 215 898-2012
200 South 33rd St.                                       Fax: +1 215 898-0587
Philadelphia, PA 19104, USA                http://www.cis.upenn.edu/~bcpierce
-----------------------------------------------------------------------------





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

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

[Maxence Guesdon]

> 
>      (** 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.


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

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

[Sven]

On Wed, Oct 10, 2001 at 01:07:19PM -0400, Patrick M Doane wrote:
> On Wed, 10 Oct 2001, Benjamin C. Pierce wrote:
> 
> > I.e., *one* kind of (not very) funny comment marker, plus using the
> > indentation to decide whether the comment binds to the expression before
> > or after:
> > 
> >       if the comment is on a line by itself, 
> >       then if its indentation is the same as the following (non-comment) line
> >            then it goes with the following
> >            else it goes with the preceding
> >       else it goes with the line it's on.
> 
> This proposal looks perfect to me.
> 
> I've also noticed in the manual that all of the multi-line comment
> examples are like this:
> 
>  (**  line 1
>       line 2
>       line 3 *)
> 
> Will there be any issues with writing comments like this?
> 
>  (** line 1
>   *  line 2
>   *  line 3
>   *)

Yes, this is nice, and the extra * may even be provided by your editor
automatically, like what happens with C code, provided the corresponding
vim/emacs rules are extended accordyingly (but then maybe vim 6 can already do
thi ?).

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

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

[Patrick M Doane]

On Wed, 10 Oct 2001, Benjamin C. Pierce wrote:

> I would have preferred a single marker meaning "escape to raw hevea [or
> whatever] and let me do whatever I want at this point."  This provides
> all the power that one could ever need, but discourages people from
> using it more than occasionally -- a Good Thing. 

One important issue here is that author A may want to escape to LaTeX and
author B may want to escape to HTML. Are you suggesting that there
should be only one escape language or one escape sequence that brings you
to whatever language the author wants to use?

The latter may cause difficulties with code integration, but certainly
keeps the symbol count low.

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

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

[Patrick M Doane]

On Wed, 10 Oct 2001, Benjamin C. Pierce wrote:

> I.e., *one* kind of (not very) funny comment marker, plus using the
> indentation to decide whether the comment binds to the expression before
> or after:
> 
>       if the comment is on a line by itself, 
>       then if its indentation is the same as the following (non-comment) line
>            then it goes with the following
>            else it goes with the preceding
>       else it goes with the line it's on.

This proposal looks perfect to me.

I've also noticed in the manual that all of the multi-line comment
examples are like this:

 (**  line 1
      line 2
      line 3 *)

Will there be any issues with writing comments like this?

 (** line 1
  *  line 2
  *  line 3
  *)

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

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

[Stefano Lanzavecchia]

> No, I meant, anyone who writes comments before the thing that they 
> refer to *and* indented more than the thing that follows them.

Right! I see now... Sorry for having added to the confusion. I agree
your proposal would perfectly cover my style. Thanks for taking time to
reply.
-- 
WildHeart'2k1 - mailto:stf@apl.it
Homepage: http://come.to/wildheart/

<<<E' che mi e' entrata una bruschetta nell'occhio ---
   Elio e le Storie Tese - Servi della Gleba>>>

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

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

[Benjamin C. Pierce]

> > Is there *anyone* that wants to write
> > 
> >       (* Comment for f *)
> >   val f : t
> >       (* Comment for g *)
> >   val g : t'
> 
> You mean, anyone who normally, when writing programs, either puts the
> comment before the thing being commented, or 
> 
>    val f : t  (* Comment for f *)
>    val g : t' (* Comment for g *)
> 
> on the same line as the thing being commented? 

No, I meant, anyone who writes comments before the thing that they refer
to *and* indented more than the thing that follows them.

My proposed rule

    if the comment is on a line by itself, 
    then if its indentation is the same as the following (non-comment) line
         then it goes with the following
         else it goes with the preceding
    else it goes with the line it's on.

handles your style just fine, I think.  The idea was to support all three
"natural" styles, i.e.

     (** 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.

   B



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

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

[Thorsten Ohl]

> Is there *anyone* that wants to write
> 
>       (* Comment for f *)
>   val f : t
>       (* Comment for f *)
>   val g : t'

I do.  Does this mean that I should find some professional help?

Seriously, I have formed this habit, because I've written almost all
my code in the last decade with noweb or other literate pogramming
tools derived from Don Knuth's WEB.  These encourage to write
documentation before the corresponding code and I've kept this habit
for signatures as well.
-- 
Thorsten Ohl, Physics Department, TU Darmstadt -- ohl@hep.tu-darmstadt.de
http://heplix.ikp.physik.tu-darmstadt.de/~ohl/ [<=== PGP public key here]
-------------------
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

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

[Marcin 'Qrczak' Kowalczyk]

Wed, 10 Oct 2001 11:12:17 EDT, Benjamin C. Pierce <bcpierce@saul.cis.upenn.edu> pisze:

>    - A way of marking "OCaml stuff" when it occurs inside comments,
>      e.g. by enclosing it in square brackets, so that the doc tool knows
>      to set it in a different font (and can maybe try to parse it, find
>      identifiers, index, hyperlink, etc.)

Larger parts of code might be marked by being indented inside the
comment.

Turbo Pascal used a similar convention in its help: text written at the
left margin was being broken into likes wrt. the current window width
(and would be typeset with a proportional font if it was possible -
well, it was not possible in the text mode) and lines beginning with
some spaces were treated as preformatted (tables, code).

-- 
 __("<  Marcin Kowalczyk * qrczak@knm.org.pl http://qrczak.ids.net.pl/
 \__/
  ^^                      SYGNATURA ZASTĘPCZA
QRCZAK

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

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

[Benjamin C. Pierce]

I meant, of course

      (* Comment for f *)
  val f : t
      (* Comment for g *)    (* (not f) *)
  val g : t'

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

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

[Stefano Lanzavecchia]

> Is there *anyone* that wants to write
> 
>       (* Comment for f *)
>   val f : t
>       (* Comment for g *)
>   val g : t'

You mean, anyone who normally, when writing programs, either puts the
comment before the thing being commented, or 

   val f : t  (* Comment for f *)
   val g : t' (* Comment for g *)

on the same line as the thing being commented? Yes, that's me. I
consistently either put the comment on the lines before or on the same
line as. If I ever need to put a comment after the thing being commented
I use big warnings in my source code listings, to indicate that I am
talking about what appears before (read: above) the line containing the
comment.

WARNING: I am not an OCaml programmer. I program in other languages and
only follow this maillist because I'd love to learn enough OCaml to use
to solve some of my problems.

-- 
WildHeart'2k1 - mailto:stf@apl.it
Homepage: http://come.to/wildheart/

<<<All I Ever Learned, I Learned From Anime: ---
   All magical swords are as tall, or taller, than the wielder.>>>

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

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

[Benjamin C. Pierce]

> Personnaly, i would be very strongly against using indentation to define if
> the stuff is before or after, after all, not everyone wants to indent things
> the same way.

Is there *anyone* that wants to write

      (* Comment for f *)
  val f : t
      (* Comment for f *)
  val g : t'

?  These are the only people that should be unhappy with my proposed rule.

> The (*< and (*> idea seems good and very intuitive. what is the reproch
> against it you have ?

I don't want all sorts of funny characters lying around in my comments
when I read/write .mli files.  It's very easy for this sort of tool to
get out of control and turn the source files into full-blown markup
language that can be used to produce all sorts of cool and powerful
effects in the docs, but that looks ugly when you read it in the text
editor.  So I'm resisting taking even one step onto the slippery slope.

What I'd really like to have is
   - A rule for distinguishing "documentation comments" from all other
     comments 
   - A way of marking "OCaml stuff" when it occurs inside comments,
     e.g. by enclosing it in square brackets, so that the doc tool knows
     to set it in a different font (and can maybe try to parse it, find
     identifiers, index, hyperlink, etc.)
   - That's all!

>From the OCamlDoc manual, I see that the present design of the tool does,
in fact, go quite a few steps further than the point where I could have
stopped.  Instead of putting in all these little markup commands, I would
have preferred a single marker meaning "escape to raw hevea [or whatever]
and let me do whatever I want at this point."  This provides all the
power that one could ever need, but discourages people from using it more
than occasionally -- a Good Thing.  However, I think the current design
is actually a pretty reasonable compromise between what I want and what
other (more feature-loving :-) people might like.  It allows me to
produce *reasonable* docs with *simple* (and not very ugly) mechanisms,
while allowing others to produce pretties docs at some cost in ugliness
of the sources.  Please let's try to keep this property!

     Benjamin



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

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

[Jacques Garrigue]

From: Sven <luther@dpt-info.u-strasbg.fr>
> On Wed, Oct 10, 2001 at 07:08:05AM -0400, Benjamin C. Pierce wrote:
> > 
> > I.e., *one* kind of (not very) funny comment marker, plus using the
> > indentation to decide whether the comment binds to the expression before
> > or after:
> > 
> >       if the comment is on a line by itself, 
> >       then if its indentation is the same as the following (non-comment) line
> >            then it goes with the following
> >            else it goes with the preceding
> >       else it goes with the line it's on.
> 
> Personnaly, i would be very strongly against using indentation to define if
> the stuff is before or after, after all, not everyone wants to indent things
> the same way.

I think that the above rules match rather closely what most people
write anyway. A documentation tool is based on conventions, as visual
as possible (you want to read the comments in the source too).

And I understand Benjamin Pierce's resistance to a multiplication of
strange symbols: they are harder to read than indentation.

But what am I doing in a discussion on automatic documentation, while
I almost never write any comment :-(

Cheers,

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

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

[Sven]

On Wed, Oct 10, 2001 at 07:08:05AM -0400, Benjamin C. Pierce wrote:
> > I think you missed the point of Jerome's suggestion, which was (** ...
> > *) vs. (* ... **).  (Either that, or I missed his point...).  So my
> > variant was to show the difference at the start of each comment, where
> > it would be more immediate.
> 
> Aha -- sorry, I did miss the point.  So I'd like to make another a
> variant proposal... :-)
> 
>   - The comment is before the element:
>         (** fun 1 *)
>         val f : t
>         (** fun 2 *)
>         val g : u
> 
>   - The comment is after the element:
>         val f : t
>           (** fun 1 *)
>         val g : u
>           (** fun 2 *)
> 
>   - The comment is on the same line as the element:
>         val f : t   (** fun 1 *)
>         val g : u   (** fun 2 *)
>     (Most useful for record fields, probably.)
> 
> I.e., *one* kind of (not very) funny comment marker, plus using the
> indentation to decide whether the comment binds to the expression before
> or after:
> 
>       if the comment is on a line by itself, 
>       then if its indentation is the same as the following (non-comment) line
>            then it goes with the following
>            else it goes with the preceding
>       else it goes with the line it's on.

Personnaly, i would be very strongly against using indentation to define if
the stuff is before or after, after all, not everyone wants to indent things
the same way.

The (*< and (*> idea seems good and very intuitive. what is the reproch
against it you have ?

Another idea would be (but more cumbersome, and much less readable) :

(** comment before *)

(* comment after **)

or even (*< comment before **) and (** comment before >*)
(or maybe the other way around)

But still this is less handy when longer comments are used.

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

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

[Sven]

On Tue, Oct 09, 2001 at 01:26:38PM -0400, Maxence Guesdon wrote:
> Dave Berry wrote:
> > Would it be possible for OCamldoc to detect whether the comment follows
> > a definition on the same line?  If so, then you could use this to infer
> > that the comment refers to that definition.  If the comment begins on a
> > new line, the comment would refer to the following definition.
> > 
> 
> In some case, you want to start the comment on the line after, because 
> it 's a long comment, maybe on more than one line, like in
> 
> type t =
>    C of int
>      (** my long comment i didn't want ot start on the line above. *)
> | C2
> 
> so here we don't want to associate this comment to C2 but to C.

But this same argument could be reversed :

type t = 
    C of <insert very long multi line type here>
      (** short comment **)

Here, it makes more sense to have it first.

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

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

[Benjamin C. Pierce]

> I think you missed the point of Jerome's suggestion, which was (** ...
> *) vs. (* ... **).  (Either that, or I missed his point...).  So my
> variant was to show the difference at the start of each comment, where
> it would be more immediate.

Aha -- sorry, I did miss the point.  So I'd like to make another a
variant proposal... :-)

  - The comment is before the element:
        (** fun 1 *)
        val f : t
        (** fun 2 *)
        val g : u

  - The comment is after the element:
        val f : t
          (** fun 1 *)
        val g : u
          (** fun 2 *)

  - The comment is on the same line as the element:
        val f : t   (** fun 1 *)
        val g : u   (** fun 2 *)
    (Most useful for record fields, probably.)

I.e., *one* kind of (not very) funny comment marker, plus using the
indentation to decide whether the comment binds to the expression before
or after:

      if the comment is on a line by itself, 
      then if its indentation is the same as the following (non-comment) line
           then it goes with the following
           else it goes with the preceding
      else it goes with the line it's on.

  -- B

-----------------------------------------------------------------------------
BENJAMIN C. PIERCE
Associate Prof., Computer & Information Science        bcpierce@cis.upenn.edu
University of Pennsylvania                                    +1 215 898-2012
200 South 33rd St.                                       Fax: +1 215 898-0587
Philadelphia, PA 19104, USA                http://www.cis.upenn.edu/~bcpierce
-----------------------------------------------------------------------------







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

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

[Maxence Guesdon]

Dave Berry wrote:
> Would it be possible for OCamldoc to detect whether the comment follows
> a definition on the same line?  If so, then you could use this to infer
> that the comment refers to that definition.  If the comment begins on a
> new line, the comment would refer to the following definition.
> 

In some case, you want to start the comment on the line after, because 
it 's a long comment, maybe on more than one line, like in

type t =
   C of int
     (** my long comment i didn't want ot start on the line above. *)
| C2

so here we don't want to associate this comment to C2 but to C.

--
Maxence


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

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

[Dave Berry]

I think you missed the point of Jerome's suggestion, which was (** ...
*) vs. (* ... **).  (Either that, or I missed his point...).  So my
variant was to show the difference at the start of each comment, where
it would be more immediate.

Anyway, we're not talking about a dozen markers, just two: one for
comments that precede items, and one for comments that follow them.
Admittedly my variant uses two more characters, and could be considered
more intrusive for that reason.

Dave.

-----Original Message-----
From: Benjamin C. Pierce [mailto:bcpierce@saul.cis.upenn.edu]
Sent: 09 October 2001 13:14
To: Dave Berry
Cc: Maxence Guesdon; Jerome Vouillon; Francois Pottier;
caml-list@inria.fr
Subject: Re: [Caml-list] Re: [Caml-announce] OCamldoc 

Let me enter a plea here for *not* introducing a dozen different kinds
of
funny markers in comments.  One of the nice features of the original
proposal was that it doesn't uglify the source code very much -- please
let's keep that.

For the record, I like Jerome's idea of using just indentation to figure
out which comment goes with which declaration.

      B


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

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

[Benjamin C. Pierce]

> How about a variation on Jerome's suggestion:
> 
> - The comment is before the element:
>       (*> fun 1 *)
>       val f : t
>       (*> fun 2 *)
>       val g : u
> - The comment is after the element:
>       val f : t
>         (*< fun 1 *)
>       val g : u
>         (*< fun 2 *)

Let me enter a plea here for *not* introducing a dozen different kinds of
funny markers in comments.  One of the nice features of the original
proposal was that it doesn't uglify the source code very much -- please
let's keep that.

For the record, I like Jerome's idea of using just indentation to figure
out which comment goes with which declaration.

      B


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

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

[Dave Berry]

How about a variation on Jerome's suggestion:

- The comment is before the element:
      (*> fun 1 *)
      val f : t
      (*> fun 2 *)
      val g : u
- The comment is after the element:
      val f : t
        (*< fun 1 *)
      val g : u
        (*< fun 2 *)

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

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

[Dave Berry]

Would it be possible for OCamldoc to detect whether the comment follows
a definition on the same line?  If so, then you could use this to infer
that the comment refers to that definition.  If the comment begins on a
new line, the comment would refer to the following definition.

Dave.

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