[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

[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

[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

[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

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

[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

[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