Mantis Bug Tracker

View Issue Details Jump to Notes ] Issue History ] Print ]
IDProjectCategoryView StatusDate SubmittedLast Update
0007825OCamldocumentationpublic2018-07-17 22:442018-09-12 09:57
Reportergasche 
Assigned Tooctachron 
PrioritynormalSeveritytextReproducibilitysometimes
StatusresolvedResolutionfixed 
PlatformOSOS Version
Product Version 
Target Version4.08.0+devFixed in Version4.08.0+dev 
Summary0007825: In the manual, some beginners think that the compiler-libs modules are part of the standard library
DescriptionWitness 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.
TagsNo tags attached.
Attached Files

- Relationships
related to 0007247resolvedoctachron Compiler internals exported as standard library modules in documentation 

-  Notes
(0019260)
xleroy (administrator)
2018-07-19 18:03

> 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.
(0019315)
octachron (developer)
2018-08-24 01:56

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.
(0019337)
octachron (developer)
2018-09-03 17:05

See https://github.com/ocaml/ocaml/pull/2017 [^] for an implementation of the proposal above.
(0019361)
gasche (administrator)
2018-09-12 09:56

Fixed by octachron's PR above. Thanks!
(0019362)
octachron (developer)
2018-09-12 09:57

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.

- Issue History
Date Modified Username Field Change
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
Powered by Mantis Bugtracker