[Opa] documentation for database functions

[N Owen Gunden]

On Wed, Jan 18, 2012 at 11:15:57AM +0100, Frederic Ye wrote:
> On Jan 18, 2012, at 3:25 AM, N Owen Gunden wrote:
> >  Db.intmap_fold_range(path_t(α, map(int, β)) _, (γ, int → γ) _, γ _, int _, option(int) _, (int → bool) _)
> >
> > What is with all the '_' characters in that type signature?
>
> '_' means unamed argument.
> Indeed if you look at the source code
> (https://github.com/MLstate/opalang/blob/master/stdlib/core/db/db.opa#L183),
> intmap_fold_range is a bypass, and we can not retrieve bypasses
> parameters name.

Got it.

> > Bug in the documentation generator or is the doc comment misformatted?
>
> The doc comment is misplaced here, we changed our doc system, and
> this placement does not work anymore.  For your information (in case
> you want to submit pull-request one day ;)), you have to append the
> comment to the function :
> 
> /**
>  * MY DESCRIPTION
>  */
> my_function(p1, p2, ...) = ...

Good to know! [I'll have to get opa to compile before I can submit
patches though (I still run into issues because I use godi and hence
my ocaml libraries are in two different locations).]

> > 2. Clicking through to the source code, it reads:
> >
> > /**
> > * Folds on a map with a range and a filter;
> > * @param [f] function to be applied to every element of the map.
> > * @param [start] where to start the fold, boundary included. 0 is the first key of the map.
> > * @param [ending] where to stop, boundary not included. [none] is ending at the last key of the map,
> > * [some(3)] is stopping at the second key of the map.
> > * @param [filter] which keys are accepted for the fold. (x -> {true}) is all the keys of the map
> > * are accepted.
> > */
> >
> > This makes sense for intmap_fold_range, but I don't see how [start]
> > and [ending] are interpreted by stringmap_fold_range. It seems odd
> > that [start] is a string while [ending] is an int option. Are the
> > string keys lined up in lexicographic order or something? I could read
> > the code, but I guess my point is that I hope eventually I wouldn't
> > have to..
>
> This comment is for intmap_fold_range only.

Okay, so what is the meaning of the params [start] and [ending] for
stringmap_fold_range?

> For returning an option type :
>
> ?/my_map[key]

As I mentioned in the other thread, this is awesome, I just couldn't
find it.