[Caml-list] ocaml doc

[Caml-list] ocaml doc

[John Skaller]

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?

It also won't label polymorphic variant components ..
type X = [
	| `A (** an A *)
	| `B (** a B *)
]

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

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.

-- 
John Max Skaller, mailto:skaller@ozemail.com.au
snail:10/1 Toxteth Rd, Glebe, NSW 2037, Australia.
voice:61-2-9660-0850


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

Re: [Caml-list] ocaml doc

[Maxence Guesdon]

> 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

Re: [Caml-list] ocaml doc

[Maxence Guesdon]

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

The output is ok for values, but was left-flushed for types. This is corrected
in the CVS version.

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