Mantis Bug Tracker

View Issue Details Jump to Notes ] Issue History ] Print ]
IDProjectCategoryView StatusDate SubmittedLast Update
0006471OCamlOCamldocpublic2014-06-25 23:492014-07-11 13:27
Reporterdbuenzli 
Assigned Toguesdon 
PrioritynormalSeverityminorReproducibilityalways
StatusassignedResolutionfixed 
PlatformOSOS Version
Product Version4.02.0+beta1 / +rc1 
Target Versionafter-4.02.0Fixed in Version 
Summary0006471: ocamldoc doesn't support module aliases
Descriptionmkdir /tmp/test
cd /tmp/test
echo "module B = Test_b" > test.mli
echo "(** Module B synopsis *)" > test_b.mli
ocamlc test.mli
ocamlc test_b.mli
ocamldoc -html test.mli

I expect to be able to jump in the documentation of test_b.mli when I click on B in the documentation of Test.
Steps To ReproduceFixed in rev 14992 in version/4.02 branch. It also fixes missing links for module aliases with no dot in the aliased module name.
Can you give it a try ?
TagsNo tags attached.
Attached Files

- Relationships

-  Notes
(0011778)
dbuenzli (reporter)
2014-06-26 15:12

I tried and I'd say that from a documentation/usability perspective it's not very good for the following reasons.

1. The *module type* is now linked to the documentation of the concrete module but I don't really want to click on that, I want to click on the *module name*, currently doing that just points me to a useless, mostly empty page, but it's on this page that I expect to find the contents of the documentation of the module concrete module defining the alias. To take the example above, on the page of Test I want that clicking on B takes me to the documentation contents of the concrete module Test_B and on the Test page I would also like B to have the synopsis of the module Test_B

2. Since you also need to provide the concrete module defining the alias on the command line. It also gets an entry in the toplevel list of modules. But that only adds noise to the whole thing. Module aliases are supposed to provide us with a way of defining name spaces with the module system without having to link everything in, so in some sense I'm never interested in seeing the name of the concrete modules (the right hand sides of aliases), I'm not really interested in knowing that these names exist as I would only like to access them through a single module (the name space defining module) that gather aliases.
(0011779)
guesdon (manager)
2014-06-27 08:17
edited on: 2014-06-27 08:18

Ok, I understand.

Regarding point 2., there are two options:
a) explicitely mark aliased modules with something like @hide in their comment so they don't appear in the module list (and their documentation is not generated).

b) add one pass to look for aliased modules, to automatically mark them as not being generated and not appearing in the module list. This may be problematic if you want aliased module but still want them to appear in the list. An additional command line switch could prevent aliased module from being hidden.

I still have to test about the way I can use information from module A in module B when we have module B = A .


- Issue History
Date Modified Username Field Change
2014-06-25 23:49 dbuenzli New Issue
2014-06-25 23:49 dbuenzli Status new => assigned
2014-06-25 23:49 dbuenzli Assigned To => guesdon
2014-06-26 09:58 guesdon Reproducibility have not tried => always
2014-06-26 09:58 guesdon Status assigned => resolved
2014-06-26 09:58 guesdon Resolution open => fixed
2014-06-26 09:58 guesdon Steps to Reproduce Updated View Revisions
2014-06-26 15:12 dbuenzli Note Added: 0011778
2014-06-27 08:17 guesdon Note Added: 0011779
2014-06-27 08:17 guesdon Status resolved => assigned
2014-06-27 08:18 guesdon Note Edited: 0011779 View Revisions
2014-07-11 13:27 doligez Target Version => after-4.02.0


Copyright © 2000 - 2011 MantisBT Group
Powered by Mantis Bugtracker