|Anonymous | Login | Signup for a new account||2018-12-13 02:29 CET|
|Main | My View | View Issues | Change Log | Roadmap|
|View Issue Details|
|ID||Project||Category||View Status||Date Submitted||Last Update|
|0007825||OCaml||documentation||public||2018-07-17 22:44||2018-09-12 09:57|
|Target Version||4.08.0+dev||Fixed in Version||4.08.0+dev|
|Summary||0007825: In the manual, some beginners think that the compiler-libs modules are part of the standard library|
|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,
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.
|Tags||No tags attached.|
> 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.
|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.|
|See https://github.com/ocaml/ocaml/pull/2017 [^] for an implementation of the proposal above.|
|Fixed by octachron's PR above. Thanks!|
|Between the above PR and https://github.com/ocaml/ocaml/pull/2020, [^] I think that the distinction between compiler-libs and the standard library is much clearer. Hopefully, it will be enough.|
|2018-07-17 22:44||gasche||New Issue|
|2018-07-18 21:06||octachron||Relationship added||related to 0007247|
|2018-07-19 18:03||xleroy||Note Added: 0019260|
|2018-07-19 18:03||xleroy||Status||new => acknowledged|
|2018-08-24 01:56||octachron||Note Added: 0019315|
|2018-09-03 17:05||octachron||Note Added: 0019337|
|2018-09-12 09:56||gasche||Note Added: 0019361|
|2018-09-12 09:56||gasche||Status||acknowledged => resolved|
|2018-09-12 09:56||gasche||Fixed in Version||=> 4.08.0+dev|
|2018-09-12 09:56||gasche||Resolution||open => fixed|
|2018-09-12 09:56||gasche||Assigned To||=> octachron|
|2018-09-12 09:57||octachron||Note Added: 0019362|
|Copyright © 2000 - 2011 MantisBT Group|