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
Assigned Tooctachron 
PlatformOSOS Version
Product Version 
Target Version4.08.0+dev/beta1Fixed in Version4.08.0+dev/beta1 
Summary0007825: In the manual, some beginners think that the compiler-libs modules are part of the standard library
DescriptionWitness this reddit question ( [^] ) 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, [^]

or [^]

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

See [^] for an implementation of the proposal above.
gasche (administrator)
2018-09-12 09:56

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

Between the above PR and, [^] 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/beta1
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