0004347: Seems not possible to comment each case of polymorphic variant types ?

Notes
(0004134) jm (reporter) 2007-08-13 09:22 edited on: 2007-08-14 14:12	Unfortunately, as I see it, if you want to do it properly/completely, this would require to wrap the ubiquitous type [Types.type_expr], to convert/wrap a lot of functions of ocamldoc/ocaml currently using this type, to retrieve the comments (not easy since the locations are not kept inside [Parsetree.core_type_desc]), to associate the comments in the wrapped type (with all the difficulty caused by the nested polymophic variant types), and finally to copy/extend Oprint and Printtyp, plus a few other modules. This task is not unfeasible, but is not easy and requires a lot of changes, increasing, to my mind, a little too much the size and complexity of ocamldoc for such a little gain. Therefore, in my humble opinion, your wish will not be fulfilled.

(0004137) jm (reporter) 2007-08-16 18:44 edited on: 2007-08-16 18:55	Here, I've written a little patch that should do the job, but only on type declaration. NB: This patch may contain bugs, and might slow down ocamldoc; I am no ocamldoc/ocamlc expert, and I have only tested it against this example: module M0 : sig type t = [`M0tA (** com M0tA )] end type n = [ `NA (* com NA ) \| `NB (* com NB ) ] type 'a t = [ `F of ([>`A (* com FA ) \| n (* com Fn ) ] as 'a ) (* com F ) \| `A of int (* com A ) \| `B of int (* com B ) \| `C of int (* com C ) \| `D of [`A (* com DA ) \|`B (* com DB ) ] (* com D ) \| `E of ( [`A (* com E0A )] [`A (** com E1A )] ( <m:[`A (** com E20m0A )] -> [`A (* com E20m1A)] -> [`A (* com E20m2A)]> <m:[ `A (** com E21mA ) \| `B of (int [`A (** com E21mB1A )]) (* com E21mB )]> ) ) (* com E ) \| n (* com n ) \| M0.t (* com M0.t ) ] int By the way, [Printtyp.type_scheme_max] is not used any longer, but since it does not really belong to ocamldoc, this patch does not remove it.

(0004138) jm (reporter) 2007-08-17 15:07 edited on: 2007-08-18 23:24	As foreseen, there are at least 4 bugs in ocamldoc_poly_var.patch: 1/ Due to my misunderstanding of ocamlc, the polymorphic symbols are not reset properly, which creates this kind of ugly thing: val f : 'a -> 'a val g : 'b -> 'b I think it is related to reset_names, but I really don't know currently. EDIT: this was indeed due to not resetting a few internal variables: it was done for Printtyp's vars instead of Odoc_print's ones. FIX_ocamldoc_poly_var_proxies.patch should correct this. 2/ Due to my laziness, the comments in the implementation file are not merge with the comments in the interface file. EDIT: fixed in FIX_ocamldoc_merge_of_type_manifest_comments.patch, which also brings better names and removes useless debugging calls and tabulations. 3/ Due to my bad use of git, the patch changes .depend instead of Makefile. EDIT: fixed in FIX_ocamldoc_poly_var_proxies.patch 4/ For the HTML output, the {!<name>} references are not set properly. For instance: let f () = () type t = [`A (** start {!f} between {!g} end )] let g () = () Gives: [...] <code class="type">[ `A <td class="typefieldcomment" align="left" valign="top" ><code>(</code></td><td class="typefieldcomment" align="left" valign="top" >start <code class="code">f</code> between <code class="code">g</code> end</td><td class="typefieldcomment" align="left" valign="bottom" ><code>*)</code></td> ]</code> [...] "href" are missing :/ EDIT: fixed in FIX_ocamldoc_cross_referencing.patch. By the way, it removes a lot of code in Odoc_print, 'cause I was being moron when I thought Printtyp had to be copied. It also removes more useless debugging calls, and improves a few names.

(0004139) jm (reporter) 2007-08-18 23:29 edited on: 2007-08-20 00:27	GLOBAL_ocamldoc_type_manifest_comments.patch sums up all the previous patches. 5/ Due to my lack of reflexion, nested polymorphic variant types completely mess up the comments. Example 1: module X = struct type x = [`A (** X.x A )] end type x = [`A (* x A )] open X type t = [ x (* t x ) \| `B (* t B )] Gives: module X : sig type x = [ `A ( X.x A ) ] end type x = [ `A ( x A ) ] type t = [ `A ( x A t x ) <--- the "x A" should be "X.x A" \| `B ( t B ) ] Exemple 2: type s = [`A (* s A )] module M = struct type u = [ s (* M.u s ) \| `B (* M.u B )] end Currently end up on an [assert false]. Should produce: module M : sig type u = [ `A ( s A M.u s ) \| `B ( M.u B *) ] EDIT: fixed in FIX_ident_management.patch. It was sufficient to use the Odoc_env machinery... Besides, it improves a few names, and removes dependencies to non-existent files: odoc_outcometree.ml, odoc_btype.ml and odoc_ctype.ml, which were deprecated files in my repository I had forgotten to delete. And besides, http://caml.inria.fr/mantis/view.php?id=4366 [^] may bite too.

(0004140) jm (reporter) 2007-08-20 00:29 edited on: 2007-08-21 08:19	Release candidate 5: ocamldoc-type_manifest_comments-rc5.patch sums up all the previous patches. 6/ nested p. v. types support is still too weak EDIT: improved in FIX_ocamldoc_nested_poly_var_types.patch but there are still problems with types in functors and [open] on an external module.

(0004141) jm (reporter) 2007-08-21 08:20	Release candidate 6: ocamldoc-type_manifest_comments-rc6.patch sums up all the previous patches.

(0004142) jm (reporter) 2007-08-22 17:27	So, as I read the source of ocamldoc and try to understand how it works, it seems that odoc_sig.ml and odoc_ast.ml are not aware of external modules. And that it is too much work for me to properly make them so. It's a shame because that easily allows completely wrong output. This, plus the lack of orthogonality between [module] and [module type], plus the weird/incomplete support of [open], [include] and functors make me deeply sad to the point of not using ocamldoc at all and get stuck with raw .mli/.ml, which, sure, do not have clickable-links, but which do not lie. I'll just add the last RC, which corrects a few things about comments in p. v. types and cross-referencing in functors. And wish courage to anyone desiring to improve/fix ocamldoc.

Issue History
Date Modified	Username	Field	Change
2007-07-18 09:54	matt	New Issue
2007-08-13 09:22	jm	Note Added: 0004134
2007-08-13 09:22	jm	Note Edited: 0004134
2007-08-14 14:12	jm	Note Edited: 0004134
2007-08-16 18:33	jm	File Added: ocamldoc_poly_var.patch
2007-08-16 18:44	jm	Note Added: 0004137
2007-08-16 18:55	jm	Note Edited: 0004137
2007-08-17 15:07	jm	Note Added: 0004138
2007-08-17 18:56	jm	File Added: FIX_ocamldoc_poly_var_proxies.patch
2007-08-17 19:00	jm	Note Edited: 0004138
2007-08-17 19:01	jm	Note Edited: 0004138
2007-08-17 19:04	jm	Note Edited: 0004138
2007-08-18 13:41	jm	File Added: FIX_ocamldoc_merge_of_type_manifest_comments.patch
2007-08-18 13:47	jm	Note Edited: 0004138
2007-08-18 18:40	jm	Note Edited: 0004138
2007-08-18 23:17	jm	File Added: FIX_ocamldoc_cross_referencing.patch
2007-08-18 23:24	jm	Note Edited: 0004138
2007-08-18 23:25	jm	File Added: GLOBAL_ocamldoc_type_manifest_comments.patch
2007-08-18 23:29	jm	Note Added: 0004139
2007-08-19 20:06	jm	Note Edited: 0004139
2007-08-20 00:10	jm	File Added: FIX_ident_management.patch
2007-08-20 00:16	jm	File Added: ocamldoc-type_manifest_comments-rc5.patch
2007-08-20 00:27	jm	Note Edited: 0004139
2007-08-20 00:29	jm	Note Added: 0004140
2007-08-21 08:14	jm	File Added: FIX_ocamldoc_nested_poly_var_types.patch
2007-08-21 08:15	jm	File Added: ocamldoc-type_manifest_comments-rc6.patch
2007-08-21 08:19	jm	Note Edited: 0004140
2007-08-21 08:20	jm	Note Added: 0004141
2007-08-22 17:27	jm	Note Added: 0004142
2007-08-22 17:28	jm	File Added: FIX_ocamldoc_functor_cross_ref_and_merge_labels.patch
2007-08-22 17:28	jm	File Added: ocamldoc-type_manifest_comments-rc7.patch
2007-11-10 14:54	xleroy	Status	new => assigned
2007-11-10 14:54	xleroy	Assigned To	=> guesdon
2008-01-21 10:28	guesdon	Relationship added	has duplicate 0004482