Re: To be or not to be - these are the options for Option.map

Core's API is very large and there isn't a clear way to figure out what's
where and what is more or less important. I recommend a mixture of the
following techniques: i) read the html documentation [1], ii) read the mli
files, and iii) use utop's #typeof directive. Sometimes you won't find
something using one of these techniques, but another of the techniques
helps you.

This is of course terrible, and one wishes there was a single definitive
technique for obtaining well organized documentation. That isn't the case
due to: a) deficiencies in the tool that generates documentation (there is
hopefully a new project to improve this), b) Core's heavy factoring of code
into various sub-modules and functors (this is a good thing as it also
makes Core very robust and maintainable, but unfortunately is often
contrary to what a human needs to understand the code), and c) the lack of
documentation in the first place (this is improving over time, and I think
they would welcome contributions).

[1] https://ocaml.janestreet.com/ocaml-core/



On Sat, Sep 6, 2014 at 12:41 PM, Jeremy Yallop [email protected]
[ocaml_beginners] <[email protected]> wrote:

>
>
> On 6 September 2014 17:02, [email protected] [ocaml_beginners]
> <[email protected]> wrote:
> > However, looking in ~/.opam/system/lib/core_kernel/option.mli reveals no
> definition of the map function. The closest match is "val map2 : 'a t -> 'b
> t -> f:('a -> 'b -> 'c) -> 'c t".
> >
> > How can the code compile just fine when the 'map' definition isn't there?
>
> The signature for the Option module has an 'include' line:
>
> include Monad.S with type 'a t := 'a t
> https://github.com/janestreet/core_kernel/blob/5aa53f/lib/option.mli#L8
>
> This line means, roughly, "copy the contents of Monad.S at this
> point". The Monad.S signature has a map function
>
> val map : 'a t -> f:('a -> 'b) -> 'b t
> https://github.com/janestreet/core_kernel/blob/5aa53f/lib/monad.ml#L44-L45
>
> so the result of the 'include' is that Option ends up with a map
> function as well.
>
> Note that these are just the type signatures, not the actual
> definitions. The definitions themselves are found in the
> implementation files:
>
> let map =
> match M.map with
> | `Define_using_bind -> map_via_bind
> | `Custom x -> x
> https://github.com/janestreet/core_kernel/blob/5aa53f/lib/monad.ml#L64-L67
>
> However, the definition of 'map' in Core is split into several parts
> that might make it tricky to understand if you don't have a lot of
> experience reading OCaml code. It might be easier to start by looking
> at the more straightforward definition in the "batteries included"
> library:
>
> let map f = function
> | None -> None
> | Some v -> Some (f v)
>
> https://github.com/ocaml-batteries-team/batteries-included/blob/47a416/src/batOption.ml#L36-L38
>  
>