Mantis Bug Tracker

View Issue Details Jump to Notes ] Issue History ] Print ]
IDProjectCategoryView StatusDate SubmittedLast Update
0004347OCamlOCamldocpublic2007-07-18 09:542013-09-04 17:50
Reportermatt 
Assigned Toguesdon 
PrioritynormalSeverityfeatureReproducibilityalways
StatusassignedResolutionopen 
PlatformOSOS Version
Product Version3.09.3 
Target VersionFixed in Version 
Summary0004347: Seems not possible to comment each case of polymorphic variant types ?
Description(** General comment already taken into account *)
type my_polyvar_typ = [
`First (** comment I would like to be treated like variants comments *)
| `Second (** idem *)
]
Tagspatch
Attached Filespatch file icon ocamldoc_poly_var.patch [^] (55,662 bytes) 2007-08-16 18:33 [Show Content]
patch file icon FIX_ocamldoc_poly_var_proxies.patch [^] (13,864 bytes) 2007-08-17 18:56 [Show Content]
patch file icon FIX_ocamldoc_merge_of_type_manifest_comments.patch [^] (29,585 bytes) 2007-08-18 13:41 [Show Content]
patch file icon FIX_ocamldoc_cross_referencing.patch [^] (29,781 bytes) 2007-08-18 23:17 [Show Content]
patch file icon GLOBAL_ocamldoc_type_manifest_comments.patch [^] (61,127 bytes) 2007-08-18 23:25 [Show Content]
patch file icon FIX_ident_management.patch [^] (24,678 bytes) 2007-08-20 00:10 [Show Content]
patch file icon ocamldoc-type_manifest_comments-rc5.patch [^] (58,443 bytes) 2007-08-20 00:16 [Show Content]
patch file icon FIX_ocamldoc_nested_poly_var_types.patch [^] (48,540 bytes) 2007-08-21 08:14 [Show Content]
patch file icon ocamldoc-type_manifest_comments-rc6.patch [^] (64,775 bytes) 2007-08-21 08:15 [Show Content]
patch file icon FIX_ocamldoc_functor_cross_ref_and_merge_labels.patch [^] (5,009 bytes) 2007-08-22 17:28 [Show Content]
patch file icon ocamldoc-type_manifest_comments-rc7.patch [^] (66,210 bytes) 2007-08-22 17:28 [Show Content]

- Relationships
has duplicate 0004482closed ocamldoc does not document polymorphic variants 

-  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
2013-09-04 17:50 doligez Tag Attached: patch


Copyright © 2000 - 2011 MantisBT Group
Powered by Mantis Bugtracker