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
• bytes
• compress
• container
• crypto
• dynlib
• fmt
• hash
• image
• io
• log
• math
• mem
• odin
• path
• reflect
• runtime
• simd
• slice
• sort
• strconv
• strings
• sync
• text
• time
• thread
• unicode
• flags

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!

[flysand7]

core:simd documentation is complete.

[kelreeeeey]

Hi, I am planning to contribute to code documentation. I'm currently just started writing documentation for core:math and hopefully everythin inside it. I've forked it here (forked from Odin-master)

• core:math: in progress

---

I've made standalone dedicated repo to make example with standardize example format defined in [this comment] (#2358 (comment))

I'll write all of the example in that repo as well as the detail update of documentation there.
the standalone-dedicated repo can be found here: https://github.com/kelreeeeey/sandbox-to-contrib-odin-doc

to sum-up, below is my plan to write the docs:

1. going through https://pkg.odin-lang.org/core/math/
2. i mainly will focus on procedure groups
3. write a simple script using that procedure groups that
4. the script will
   • explain what it is
   • what types that it accepts
   • example for each type
   • as well as the output
5. Update the forked repo
6. repeat

---

for example, here the doc I wrote for math.sqrt procedure group:

// ...
/*
Will return square root of given input.

**Only accept floats**

Example:
        x_float :      = 4.0    ;    sqrt_x_float   := math.sqrt(x_float) // using default type of f16
        x_f16   :f16   = 30.90  ;    sqrt_x_f16     := math.sqrt(x_f16)
        x_f16le :f16le = 50.0   ;    sqrt_x_f16le   := math.sqrt(x_f16le)
        x_f16be :f16be = 100    ;    sqrt_x_f16be   := math.sqrt(x_f16be)
        x_f32   :f32   = 4.89   ;    sqrt_x_f32     := math.sqrt(x_f32)
        x_f32le :f32le = 3.14   ;    sqrt_x_f32le   := math.sqrt(x_f32le)
        x_f32be :f32be = 2.0    ;    sqrt_x_f32be   := math.sqrt(x_f32be)
        x_f64   :f64   = 0.0578 ;    sqrt_x_f64     := math.sqrt(x_f64)
        x_f64le :f64le = 1000.6 ;    sqrt_x_f64le   := math.sqrt(x_f64le)
        x_f64be :f64be = 89.98  ;    sqrt_x_f64be   := math.sqrt(x_f64be)

Output:
        2 // `f64`
        5.559 // `f16`
        7.07 // `f16le`
        10 // `f16be`
        2.2113345 // `f32`
        1.77200449 // `f32le`
        1.4142135 // `f32be`
        0.24041630560342614 // `f64`
        31.6322620120661 // `f64le`
        9.485778829384543 // `f64be`
*/
sqrt :: proc{
	sqrt_f16, sqrt_f16le, sqrt_f16be,
	sqrt_f32, sqrt_f32le, sqrt_f32be,
	sqrt_f64, sqrt_f64le, sqrt_f64be,
}
// ...

---

edit [1]: I opened an issue in pkg.odin-lang.org related to why I said earlier that I'll focus more on procedure groups documentation. the issue can be found here

[kelreeeeey]

I also want to know, is it possible to use simple inline latex markup when documenting?

lik, $\pi$ for $\pi$

Or it something that is not currently planned for the doc?

I think for most of the cases when documenting core:math package, it is more straight-forward to use such inline math to explain what is going on with the proc

[Kelimion]

Not supported at the moment, nor planned that I'm aware. You should be able to use the unicode math symbols as-is.

[kelreeeeey]

Thank you, very clear! Okay, we can work with that for now. well, at some point, Odin will get there, eventually.

[flysand7]

I propose we develop a proper guide for writing documentation. There's just too much inconsistency between how we document things between the packages. Variations are between the basic structure that allows tools like the documentation tester to do their job, syntactic conventions (whether fields like Inputs: and Returns are bold), and the language that is being used.

Furthermore, some of the notations we use only exist because of limitations of the tools we use on the documentation strings. One such case is putting raw text in Example: section. Instead of defining a convention for it I suggest we fix the tools.

I'll start drafting a discussion page for this. Input on that page would be highly appreciated.

[flysand7]

Discussion page for Documentation guidelines at #5039

Apparently it took me 2 hours to write, but hopefully it's a good enough start. When it's more mature I could see moving this page to project Wiki and linking .github/CONTRIBUTING.md to it.

[flysand7]

The quest for Making Documentation Great Again is ongoing. Made an issue to OLS regarding inconsistent documentation DanielGavin/ols#626