|Anonymous | Login | Signup for a new account||2014-09-02 16:27 CEST|
|Main | My View | View Issues | Change Log | Roadmap|
|View Issue Details|
|ID||Project||Category||View Status||Date Submitted||Last Update|
|0006471||OCaml||OCamldoc||public||2014-06-25 23:49||2014-07-11 13:27|
|Product Version||4.02.0+beta1 / +rc1|
|Target Version||4.02.1+dev||Fixed in Version|
|Summary||0006471: ocamldoc doesn't support module aliases|
echo "module B = Test_b" > test.mli
echo "(** Module B synopsis *)" > 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 Reproduce||Fixed 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 ?
|Tags||No tags attached.|
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.
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 .
|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||=> 4.02.1+dev|
|Copyright © 2000 - 2011 MantisBT Group|