Join GitHub today
GitHub is home to over 36 million developers working together to host and review code, manage projects, and build software together.Sign up
Better handling of objects type definition #6274
Original bug ID: 6274
Definition of object types, while syntactically similar to record types, are not "handled" by ocamldoc, i.e. the documentation one associates to fields does not appear in ocamldoc output.
I have written a few patches to implement such a feature, they are available for review at https://github.com/trefis/ocaml/tree/ocamldoc .
I'm not sure how much this is related to #4347 .
You will notice that I introduce some code duplication with the handling of records (although it might be hard to notice, considering how much code duplication there already is) which should be easily factorisable.
The patches are currently on the 4.01.0 branch, but I don't think rebasing them to trunk would pose any problem.
Comment author: @gasche
I just did a review of the patch (medium precision, I would say). It consists of three commits:
I think (commit 1) is reasonable, but I am less convinced by the overall design of (commit 2): a new "type kind" is added to the type Odoc_type.type_kind, which previously precisely mirrored the type_kind of the typedtree (type synonym, variant or record), to store the information needed by the backends.
I think it is wrong to break the correspondence between the typedtree "type kind" and ocamldoc's "type kind" (for example ocamldoc uses type_kind to decide whether to print parameters variance information, and I suspect this is broken by this change). A better design, I think, would be to add the idea that, besides the type_kind, useful printing information may come from the type manifest (the type-expression after the equal sign, if any), and have a function like
val manifest_structure : Types.type_expr -> Odoc_type.ty_manifest option
where ty_manifest would be a new type storing information for the type expressions we decide to print in a special way when they occur on the right of an equal sign -- (only) objects types for now. At printing points you could check both the kind and the manifest, and decide on both (eg. giving priority to the ty_manifest when it exists).
I think most of the current implementation could be reused, the idea is only to preserve the tight correspondence between typedtree's and ocamldoc's type_kind.
Other than that the patch looks sensible, and I don't see any reason not to include this extra feature.
Comment author: @trefis
Thank you for your comments.
I tried to follow your proposition:
I tried to make this commit as little intrusive as I could, so there is a lot of code redundancy which I then remove in the two next commits.
The code is available at the same url as before.
Comment author: @trefis
Quick update: gasche commented the previous patches directly on github.
Everything should be "OK" now.
PS: Thanks to "Ditoran2" for the random pokemon "maps". I hadn't realized mantis could be a suitable replacement to megaupload.