Odin Core Package Documentation

[Lperlind]

Current Status

Currently we're using core:strings as the playing ground for documentation. It's quite a large package so most of the groundworks on how things should be styled, minimum requirements, etc. are being tested there. Once completed it will be the de facto reference on writing documentation for the core libraries.

Odin Core Package Documentation

This issue is mainly to help track overall progress on documentation of Odin's core packages.
Bill stated that he really needs others to contribute if we want extensive coverage of all the packages.

Goals

Overall the simplest goal we can is to have all public facing procedure and type have a description of what they do (no matter how trivial the function is). This is any easy first pass that seems pretty achievable.

Ideally we extend this further and have at least 1 example of usage code with expected outputs for every procedure, etc.

Documentation Language

It would be really good if we can stick to some consistent set of rules as a goto for how to word things, we should come to an agreement at some point. I've noticed different packages explain in very different ways from one another it would be good to iteratively make things more the same.

Because everything is so different, there is no obvious example to refer to.

For now the simplest advice is "make it clear and terse, don't be clever".

Packages Checklist

Below are all the packages that need to be documented. Many packages contain a sizeable amount of documentation but are missing many functions, these are marked as incomplete.
Some packages have very little to no documentation, these are marked as not documented.
I largely glanced through https://pkg.odin-lang.org/core/ to determine the state of current things.
You can use this as some sort of a guide to what is best to work on.

We can update the checklist below as work is slowly merged into master.

• bufio: incomplete
• bytes: not documented, in progress(@Lperlind)
• compress: not documented
• container: incomplete, inconsistent language between sub-packages
• crypto: incomplete, inconsistent language between sub-packages
• dynlib: complete
• fmt: complete
• hash: not documented
• image: incomplete
• io: incomplete
• log: not documented
• math: not documented
• mem: complete
• odin: not documented
• path: incomplete
• reflect: incomplete
• runtime: incomplete
• simd: incomplete
• slice: incomplete
• sort: incomplete
• strconv: incomplete
• strings: complete
• sync: incomplete
• text: incomplete
• time: not documented
• thread: complete
• unicode: incomplete
• flags: complete

Packages that should not be documented

• c: users should refer to lib c documentation
• sys: users should refer to their platform specific documentation
• os: planned to be deprecated for os2
• thread: planned to have changes

[Lperlind]

Steps to standardise example code has been added in this PR: https://github.com/odin-lang/pkg.odin-lang.org.
If merged in I'll outline example requirements in a future comment.

[flysand7]

Requesting the following changes to be made to the list:

• simd: Work in progress (#4545)
• mem: Completed.
• thread: Completed.
• time: Completed.
• sync: Completed.

And the new packages that have been added since 2023 or were not listed in the list above:

• debug: Incomplete.
• encoding: Incomplete.
• flags: Incomplete.
• net: Incomplete.
• prof: Incomplete.
• testing: Incomplete.

[Lperlind]

Just saw this I'll update!