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

ocamldoc doesn't support module aliases #6471

Closed
vicuna opened this issue Jun 25, 2014 · 4 comments
Closed

ocamldoc doesn't support module aliases #6471

vicuna opened this issue Jun 25, 2014 · 4 comments

Comments

@vicuna
Copy link

vicuna commented Jun 25, 2014

Original bug ID: 6471
Reporter: @dbuenzli
Assigned to: @zoggy
Status: assigned (set by @zoggy on 2014-06-27T06:17:35Z)
Resolution: reopened
Priority: normal
Severity: minor
Version: 4.02.0+beta1 / +rc1
Category: ocamldoc
Monitored by: @hcarty

Bug description

mkdir /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 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 ?

@vicuna
Copy link
Author

vicuna commented Jun 26, 2014

Comment author: @dbuenzli

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.

@vicuna
Copy link
Author

vicuna commented Jun 27, 2014

Comment author: @zoggy

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 .

@dbuenzli
Copy link
Contributor

/cc @Octachron who I believe is responsible for ocamldoc these days. I'm neither sure whether this may have been solved nor whether it should be solved. I think we should focus API doc efforts on odoc so as far as I'm concerned I would move on to close this.

@Octachron
Copy link
Member

The point 2 is still unimplemented, but I agree that this feature is beyond the scope of ocamldoc maintenance.

@vicuna vicuna added the bug label Mar 20, 2019
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

3 participants