From mboxrd@z Thu Jan  1 00:00:00 1970
Received: (from majordomo@localhost) by pauillac.inria.fr (8.7.6/8.7.3) id QAA08665; Tue, 17 Jun 2003 16:18:16 +0200 (MET DST)
X-Authentication-Warning: pauillac.inria.fr: majordomo set sender to owner-caml-list@pauillac.inria.fr using -f
Received: from concorde.inria.fr (concorde.inria.fr [192.93.2.39]) by pauillac.inria.fr (8.7.6/8.7.3) with ESMTP id QAA09171 for <caml-list@pauillac.inria.fr>; Tue, 17 Jun 2003 16:18:15 +0200 (MET DST)
Received: from pauillac.inria.fr (pauillac.inria.fr [128.93.11.35])
	by concorde.inria.fr (8.11.1/8.11.1) with ESMTP id h5HEIFH11663
	for <caml-list@inria.fr>; Tue, 17 Jun 2003 16:18:15 +0200 (MET DST)
Received: from tintin.inria.fr (tintin.inria.fr [128.93.24.126]) by pauillac.inria.fr (8.7.6/8.7.3) with SMTP id QAA09087 for <caml-list@inria.fr>; Tue, 17 Jun 2003 16:18:14 +0200 (MET DST)
Date: Tue, 17 Jun 2003 16:18:14 +0200
From: Maxence Guesdon <maxence.guesdon@inria.fr>
To: caml-list@inria.fr
Subject: Re: [Caml-list] ocaml doc
Message-Id: <20030617161814.2cb787e3.maxence.guesdon@inria.fr>
In-Reply-To: <3EEEFB6E.1050002@ozemail.com.au>
References: <3EEEFB6E.1050002@ozemail.com.au>
Organization: INRIA
X-Mailer: Sylpheed version 0.8.11claws (GTK+ 1.2.10; i686-pc-linux-gnu)
Mime-Version: 1.0
Content-Type: text/plain; charset=US-ASCII
Content-Transfer-Encoding: 7bit
X-Spam: no; 0.00; maxence:01 guesdon:01 caml-list:01 ocamldoc:01 annotations:01 srcref:01 personnaly:01 -based:01 overflows:01 indented:01 val:01 ocaml:01 int:01 polymorphic:01 overflow:02 
Sender: owner-caml-list@pauillac.inria.fr
Precedence: bulk

> Ocamldoc didn't understand the following annotations:
> 
> type srcref =
>    string (** filename *) *
>    int (** line number, 1 origin *) *
>    int (** starting column, 1 origin *) *
>    int (** ending column, 1 origin *)
> 
> Anyone else think this might be useful?

Personnaly I prefer to put the description of the various elements
in the comment of the type:

(** (filename * line number * starting column * ending column) all 1-based *)
type srcref = string * int * int * int
 
> It also won't label polymorphic variant components ..
> type X = [
> 	| `A (** an A *)
> 	| `B (** a B *)
> ]

Yes this is not done yet. I'm thinking about it.
 
> but from the guide examples the following is
> supposed to work and does:
> 
> type weather =
> | Rain of int (** The comment for construtor Rain *)
> | Sun (** The comment for constructor Sun *)
> 
> -------------------------------------
> Minor qibble: the html formatting of
> function signatures isn't very sweet.
> When one overflows, the new line starts
> hard on the left margin (it should be indented).
> Also, if there is going to be an overflow,
> all the components at the top level should be
> on a separate line like:
> 
> 	val f:
> 		A -> 
> 
> 		B ->
> 		C ->
> 		D
> 
> or perhaps
> 
> 	val f:
> 		A
> 		-> B (* comment .. *)
> 		-> C (* comment .. *)

By now it gives:
val my_function : A ->
  -> B 
  -> C -> D

It's ok for me. I think it's more a matter of taste...

> Another minor quibble: I tried to latex
> the -latex output, and it couldn't find
> the style file ocamldoc.sty. I had to copy
> it manually to where I needed it. But the -html
> generator copies the style.css file where its needed.

The file style.css is generated (not copied) when you use the -html option.
I agree this is not very consistent. Does other people think the file
ocamldoc.sty should be generated by ocamldoc when the -latex option is given ?

Regards,

-- 
Maxence Guesdon

-------------------
To unsubscribe, mail caml-list-request@inria.fr Archives: http://caml.inria.fr
Bug reports: http://caml.inria.fr/bin/caml-bugs FAQ: http://caml.inria.fr/FAQ/
Beginner's list: http://groups.yahoo.com/group/ocaml_beginners