|Anonymous | Login | Signup for a new account||2018-08-20 22:22 CEST|
|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-07-19 18:03|
|Target Version||4.08.0+dev||Fixed in Version|
|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.
|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|
|Copyright © 2000 - 2011 MantisBT Group|