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
Comments
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. |
Comment author: jm Here, I've written a little patch that should do the job, but only on type declaration. module M0 : sig type n = type 'a t = 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. |
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: 2/ Due to my laziness, the comments in the implementation file 3/ Due to my bad use of git, the patch changes .depend instead of Makefile. 4/ For the HTML output, the {!} references are not set properly. Gives: |
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. type x = [ Gives: Exemple 2: Should produce: And besides, #4366 may bite too. |
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 |
Comment author: jm Release candidate 6: ocamldoc-type_manifest_comments-rc6.patch sums up all the previous patches. |
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. |
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. |
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
The text was updated successfully, but these errors were encountered: