`Core.Time` documentation is confusing
- 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
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