docs

[Gergely Szilvasy]

Hello,

A complete newbie here, apologies in advance.

I noticed a few issues with the docs:

https://ocaml.janestreet.com/ocaml-core/latest/doc/

1. The search box (upper right corner) doesn't work for me (Chrome or FF). 

2. I'm a bit confused that when I'm looking for String functions I'm supposed to look under Core_string (if that's even right). It'd be perhaps easier to overlook this if search worked.

3. I might be doing something wrong, but take, for example, String.rsplit2:

I can find a comment describing the function when I look here: https://github.com/janestreet/core_kernel/blob/master/lib/core_string.mli

However, there's nothing on the doc page about this function (or is it hidden?): https://ocaml.janestreet.com/ocaml-core/111.17.00/doc/core/#Core_string

Interestingly, a search turned this up for an older version: https://blogs.janestreet.com/ocaml-core/109.30.00/doc/core_kernel/Core_string.html

If there's anything I can help/do to fix any of these, please let me know. I'd be happy to help.

Regards,
Gergely

[Ashish Agarwal]

On Tue, Jun 24, 2014 at 10:42 AM, Gergely Szilvasy <szil...@gmail.com> wrote:

1. The search box (upper right corner) doesn't work for me (Chrome or FF).

It's not actually implemented yet [1]. The documentation tool is going to be completely reimplemented [2], so its unlikely to get fixed until the new tool is released in a few months.

[1] https://github.com/ocamllabs/opam-doc/issues/94

[2] http://lists.ocaml.org/pipermail/platform/2014-June/000499.html

 

2. I'm a bit confused that when I'm looking for String functions I'm supposed to look under Core_string (if that's even right). It'd be perhaps easier to overlook this if search worked.

Core packs its modules into a toplevel module named Core.Std. In Core.Std, they define String = Core_string. The reason they cannot call the module String in the first place is because String is already in the standard library, so that would be a name conflict. In general, all modules starting with Core_ have that prefix removed when packed into Core.Std. This is a bit annoying, but there's no straightforward workaround at this time.

3. I might be doing something wrong, but take, for example, String.rsplit2:

I can find a comment describing the function when I look here: https://github.com/janestreet/core_kernel/blob/master/lib/core_string.mli

However, there's nothing on the doc page about this function (or is it hidden?): https://ocaml.janestreet.com/ocaml-core/111.17.00/doc/core/#Core_string

Interestingly, a search turned this up for an older version: https://blogs.janestreet.com/ocaml-core/109.30.00/doc/core_kernel/Core_string.html

This is odd. Maybe someone on the Core team knows why comments are getting dropped in the generated docs.

[Yaron Minsky]

I have no clue. Looping in Leo White, who did some of the work on the
documentation generator.

FWIW: a new documentation generator is coming soon (post 4.02 release)
that should make this all much better...

y

> --
> You received this message because you are subscribed to the Google Groups
> "ocaml-core" group.
> To unsubscribe from this group and stop receiving emails from it, send an
> email to ocaml-core+...@googlegroups.com.
> For more options, visit https://groups.google.com/d/optout.

[Ben Millwood]

If you just look at the docs for Std, you can see modules there with their "real" name. This also solves the problem of having to work out whether they are in Core or Core_kernel.

https://ocaml.janestreet.com/ocaml-core/111.17.00/doc/core/#Std

[Leo White]

It looks to me like opam-doc is failing to find the ".cmt" file for
core_string.ml in core_kernel. The way these files are found in the
prototype is a bit of a hack, so its not surprising that it fails
sometimes. I'm unlikely to try fixing this problem since that time would
be better spent making the new documentation generator.

Regards,

Leo