Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Seems not possible to comment each case of polymorphic variant types ? #4347

Closed
vicuna opened this issue Jul 18, 2007 · 8 comments
Closed

Seems not possible to comment each case of polymorphic variant types ? #4347

vicuna opened this issue Jul 18, 2007 · 8 comments

Comments

@vicuna
Copy link

vicuna commented Jul 18, 2007

Original bug ID: 4347
Reporter: matt
Assigned to: @zoggy
Status: assigned (set by @xavierleroy on 2007-11-10T13:54:29Z)
Resolution: open
Priority: normal
Severity: feature
Version: 3.09.3
Category: ocamldoc
Tags: patch
Has duplicate: #4482

Bug description

(** General comment already taken into account )
type my_polyvar_typ = [
First (** comment I would like to be treated like variants comments *) | Second (
* idem *)
]

File attachments

@vicuna
Copy link
Author

vicuna commented Aug 13, 2007

Comment author: jm

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.

@vicuna
Copy link
Author

vicuna commented Aug 16, 2007

Comment author: jm

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.

@vicuna
Copy link
Author

vicuna commented Aug 17, 2007

Comment author: jm

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 {!} references are not set properly.
For instance:
let f () = ()
type t = [`A (** start {!f} between {!g} end *)]
let g () = ()

Gives:
[...]
[ `A (start f between g end) ]
[...]
"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.

@vicuna
Copy link
Author

vicuna commented Aug 18, 2007

Comment author: jm

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, #4366 may bite too.

@vicuna
Copy link
Author

vicuna commented Aug 19, 2007

Comment author: jm

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.

@vicuna
Copy link
Author

vicuna commented Aug 21, 2007

Comment author: jm

Release candidate 6: ocamldoc-type_manifest_comments-rc6.patch sums up all the previous patches.

@vicuna
Copy link
Author

vicuna commented Aug 22, 2007

Comment author: jm

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.

@github-actions
Copy link

This issue has been open one year with no activity. Consequently, it is being marked with the "stale" label. What this means is that the issue will be automatically closed in 30 days unless more comments are added or the "stale" label is removed. Comments that provide new information on the issue are especially welcome: is it still reproducible? did it appear in other contexts? how critical is it? etc.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
Development

No branches or pull requests

1 participant