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

In the manual, some beginners think that the compiler-libs modules are part of the standard library #7825

Closed
vicuna opened this issue Jul 17, 2018 · 5 comments
Assignees
Milestone

Comments

@vicuna
Copy link

vicuna commented Jul 17, 2018

Original bug ID: 7825
Reporter: @gasche
Assigned to: @Octachron
Status: resolved (set by @gasche on 2018-09-12T07:56:38Z)
Resolution: fixed
Priority: normal
Severity: text
Target version: 4.08.0+dev/beta1/beta2
Fixed in version: 4.08.0+dev/beta1/beta2
Category: documentation
Related to: #7247
Monitored by: @nojb @yakobowski

Bug description

Witness this reddit question ( https://www.reddit.com/r/ocaml/comments/8znh3d/using_location_module/ ) by giltho:

I'm building a Parser with Menhir and I'm trying to use the Location module.
However, open Location fails with the message Unbound module Location,
am I missing something ? Location isn' t part of the core library ?

If you look at the OCaml manual per-module,

https://caml.inria.fr/pub/docs/manual-ocaml-4.07/libref/Location.html

or

https://caml.inria.fr/pub/docs/manual-ocaml-4.07/libref/

it indeed isn't visible at all that some modules are part of the standard library (have an outward-facing interface with stability guarantees) and others are part of the compiler-libs (haphazard documentation, no stability from version to version).

It is important to allow people to distinguish these two kind of modules, and in fact it may have been a mistake to include the compiler-libs documentation online without a clearer separation. I think we should think about a clearer separation, and maybe revisit the idea of includling compiler-libs in the manual in this way. We could describe compiler-libs and encourage people to read .mli file, for example, which has the advantage of clearly marking the fact that they are doing something "more advanced" -- and more fragile.

@vicuna
Copy link
Author

vicuna commented Jul 19, 2018

Comment author: @xavierleroy

it may have been a mistake to include the compiler-libs documentation online without a clearer separation

Agreed. It's good to have some online docs for compiler-libs, but maybe it doesn't belong to the users' manual.

@vicuna
Copy link
Author

vicuna commented Aug 23, 2018

Comment author: @Octachron

I think another option would to split the compilation of the stdlib and compiler-libs, then the compiler-libs documentation could live in compilerlibref (for instance) whereas the index in libref would only contain references to the stdlib.

@vicuna
Copy link
Author

vicuna commented Sep 3, 2018

Comment author: @Octachron

See #2017 for an implementation of the proposal above.

@vicuna
Copy link
Author

vicuna commented Sep 12, 2018

Comment author: @gasche

Fixed by octachron's PR above. Thanks!

@vicuna vicuna closed this as completed Sep 12, 2018
@vicuna
Copy link
Author

vicuna commented Sep 12, 2018

Comment author: @Octachron

Between the above PR and #2020, I think that the distinction between compiler-libs and the standard library is much clearer. Hopefully, it will be enough.

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