Re: [Caml-list] ocaml doc

[Maxence Guesdon <maxence.guesdon@inria.fr>]

> 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