search

odin-lang / Odin

Odin Programming Language
https://odin-lang.org
BSD 3-Clause "New" or "Revised" License
6.17k stars 550 forks source link

Odin Core Package Documentation #2358

Open Lperlind opened 1 year ago

Lperlind commented 1 year ago

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.

Packages that should not be documented

Lperlind commented 1 year ago

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.