Mantis Bug Tracker

View Issue Details Jump to Notes ] Issue History ] Print ]
IDProjectCategoryView StatusDate SubmittedLast Update
0007825OCamldocumentationpublic2018-07-17 22:442018-07-19 18:03
Reportergasche 
Assigned To 
PrioritynormalSeveritytextReproducibilitysometimes
StatusacknowledgedResolutionopen 
PlatformOSOS Version
Product Version 
Target Version4.08.0+devFixed in Version 
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 0007247feedbackgasche 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.

- 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


Copyright © 2000 - 2011 MantisBT Group
Powered by Mantis Bugtracker