janestreet / janestreet/core

`Core.Time` documentation is confusing

Open
#129 2 comments 0 reactions 0 assignees View on GitHub
forwarded-to-js-devs
Dominant language
OCaml
Stars
1.3k
Forks
137
PR merge metrics
No merged PRs in 30d

Description

I'm not sure how much you can do about this, since the documentation is automatically generated and the `Time` module is complicated ([as documented here](https://github.com/janestreet/core/blob/master/src/core_time.ml#L10)).

That being said, the [`Core_time_float` documentation](https://ocaml.janestreet.com/ocaml-core/latest/doc/core/Core__/Core_time_float/index.html) is very cluttered, which makes it difficult to tell which hyperlinked module is the actual module that is exposed by `Core`.

For example, there are 3 top-level modules called `Span`. Two of these [link to the empty module](https://ocaml.janestreet.com/ocaml-core/latest/doc/core/Core__/Core_time_float/Span/index.html). One of them [links to the exposed `Span` module](https://ocaml.janestreet.com/ocaml-core/latest/doc/core/Core__/Core_time_float/Time/Span/index.html).

I'm personally pretty comfortable with OCaml, but even I had a hard time navigating this documentation. I would imagine that a beginner would have even more trouble making sense of this.

I think this should be a priority for any new documentation efforts, since it is a fundamental module when using other libraries (such as Async, which is why I was looking into `Span`). Even just adding some prose to help people navigate to the correct modules would be great.

I'm playing with Async in my free time, and if I make enough progress I'll be happy to submit a PR with some `Time` documentation.

Contributor guide

Open the contributing guide

Research direction

Start with src/core_time.ml and compare the generated Core_time_float documentation linked in the issue, focusing on the duplicate Span entries and the module exposed by Core. Clarify the intended navigation for the public Time modules, then add documentation or guidance that makes the exposed modules distinguishable and verify the generated pages are easier to follow.

Written by the indexing model from the issue text.

Assessment

Tech stack
ocaml
Domain
documentation
Issue type
Documentation
Difficulty
4/5
Estimated time
3-5 days
Activity status
Stale
Clarity
Needs clarification
Newbie friendliness
25/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.