Documentation conventions

[flysand7]

This discussion would be changed to reflect the current state of the conventions.

Changelog:

2025-05-05 - Version 2

• Fix consistency issues with bolding sections

2025-04-16 - Version 1

• Hide long examples in <details> tag.
• (I.1) Mention attaching package-level documentation to package declaration
• (I.2) Change the guidelines for documenting procedure groups
• (II.2) Full descriptions for procedures are optional
• (II.3) Avoid bolding sections
• (III) Fix formatting guidelines

2025-04-15 - Initial version

---

Context

Documentation for Odin's core packages is written alongside the code, which means there is a single source of documentation and many more consumers -- Text Editors, LSPs, Documentation testers, and pkg.odin-lang.org. This document outlines common guidelines that allow this single source of documentation to be usable for most consumers that we may care, as well as readable to the users of the core packages.

These guidelines are meant to be applied to Odin's core packages only. vendor packages are excempt from these, as they have their primary source of documentation elsewhere. Any other Odin code is encouraged to use these, but not required.

Currently, we have the following issues with documentation in the core packages:

1. Missing documentation (tracked by Odin Core Package Documentation #2358)
2. Incomplete documentation, such as single-line comments that don't completely describe procedure, or missing parts of a documentation comment.
3. Inconsistent use of notation (Formatting sections, which sections are allowed, how to format Inputs: and Returns sections etc)
4. Inconsistent use of language (Whether the first line of the doc is supposed to be written imperatively, descriptively or other, whether it is capitalized, etc)
5. Documentation is broken/unreadable on certain media, be it plaintext views, via the LSP hover provider or the pkg website.

Goals

The goal of the conventions to be defined below are as follows:

• Allow readable experience via plaintext, LSP hovers, and the pkg.odin-lang.org website.
• Reduce the variation in the format to allow doc strings being scanned by tools
• Introduce consistency into the documentation, so that the reader knows what to expect when looking up docs for any core package function

I. How to document packages

1. Package documentation

In order for a comment to be considered package documentation, it needs to directly precede the package declaration at the top of the file.

/*
The threads package.
*/
package threads

There should be only one package-level documentation comment per package. The following paragraph explains how to chose that file.

Package-level documentation should be located inside the doc.odin file inside of the package directory. This file should not contain any other declarations. If the package only consists of one file, instead of doc.odin, the package documentation may reside in that file.

1. One file in a package

   package/
   + package.odin <-- has the package documentation
   

2. More than one file in a package

   packages/
   + doc.odin <-- has the package documentation
   + file1.odin
   + file2.odin
   

2. Procedure groups

When documenting procedure groups it is important to consider the following:

• The user will typicaly call these procedures via their common group name
• The behaviour of each member of the group may differ in implementation details

Copy-pasting documentation is not a problem. The problem is not having it available conveniently when it's hidden somewhere else. Therefore it's important that both the group and its procedures, all have proper documentation treatment.

However, it is advised that each variant at least contains the short description (see below).

❌ How NOT to

sin_f16 :: <declaration>
sin_f32 :: <declaration>

/*
Compute sin of a number

<full description>
*/
sin :: proc { sin_f16, sin_f32 }

✅ How TO

/*
Compute sin of f16
*/
sin_f16 :: <declaration>

/*
Compute sin of f32
*/
sin_f32 :: <declaration>

/*
Compute sin of a number

<full description>
*/
sin :: proc { sin_f16, sin_f32 }

This should be a good balance between copy-pasting a lot of text (causing noise) and providing value for the users.

3. Structs and enums

For structs and enums, each field may want its own documentation. In this case, each field must be prepended with a documentation comment as opposed to following the field. Unlike every other documentation comment, these should be line comments.

❌ How NOT to

/*
The os-independent process handle.
*/
Process :: struct {
  pid: int, // ID of the process
  // OS handle to the process
  //
  // Note(linux): On linux the handle is a pidfd
  handle: uintptr,
}

✅ How TO

/*
The os-independent process handle.
*/
Process :: struct {
  // ID of the process
  pid: int,
  // OS handle to the process
  //
  // Note(linux): On linux the handle is a pidfd
  handle: uintptr,
}

This should make it easy to find where the documentation comments are inside of the structs, even if multiple lines are required in a doc comment.

4. OO-style API

OO-style API is quite common. I refer to the type that is associated with many procedures that operate on that type. For example, the Allocator implementations in core:mem, or the string builder in core:strings.

For these API's it is advised that the main type is given the most thorough documentation, describing how it's used, why it can be used, and how it is different from other types in the package, or otherwise.

For examples, see synchronization primitives in core:sync or the allocator implementations in core:mem. These should be done correctly on that specific front.

II. The structure of the documentation comment

The documentation comment should be a multi-line comment. The text inside of the comment should not be indented, and the /* and */ should be followed/preceded by newlines respectively.

❌ Don't use single-line comments for documentation

// Return the minimum value
min :: proc(a, b: T)

❌ Don't indent the contents of comments

/*
    Return the minimum value
*/
min :: proc(a, b: T)

✅ How TO

/*
Return the minimum value
*/
min :: proc(a, b: T)

The choice of unindented comments has to do with tools -- some markdown parsers will parse indented strings as codeblocks, and not all editors have control over that. However, it could be possible to pre-process the strings before passing them to the markdown parser, indented comments might still be open?

The insides of the comment consist of the following parts:

/*
<Short description>

<Full description>

<Notes, warnings, etc>

Inputs:
<Short descriptions of input values>

Returns:
<Short descriptions of return values>

<Maybe other sections, depending on the scope>
*/
declaration :: <declaration>

1. Short description

The short description of the procedure must fit on a single 50-80 characters long line. By looking at this line, the reader should be able to quickly tell whether this procedure is the one might want to use or not.

The short description should start with a verb in an imperative form, and form proper sentences.

❌ this procedure makes `foo` go kaboom
❌ Makes `foo` go kaboom.
❌ make `foo` go kaboom
✅ Make `foo` go kaboom.

2. Full description

The full description should describe the procedure fully. This includes how the parameters of the procedure are used to return its value, what it does under the hood, and most importantly -- why this procedure/type exists, and why you might want to use it.

Ideally, the full description mentions the parameter names from the Input sections. They should be wrapped in backticks.

Not sure: The full description should not be wrapped manually to 80 characters per line. Instead, each sentence should be written on a separate line. This makes the diffs look clean.

❌ How NOT to

/*
Return true if `c` is a character used to separate paths into directory and
file hierarchies on the current system.
*/
@(require_results)
is_path_separator :: proc(c: byte) -> bool

✅ How TO

/*
Check if character is an OS-dependent path separator

This procedure checks for whether a character `c` is used to separate directories in a path.
On unix-like platforms and wasi that usually just includes the `/` character.

**Note(windows)**: On windows `/` as well as `\` are considered path separators.
*/
@(require_results)
is_path_separator :: proc(c: byte) -> bool

Not sure: Whether to allow This procedure prefix. I don't, aesthetically speaking, like two lines starting with same words, so I'm using it for that purpose.

3. Inputs and Returns

This sections purpose is to link the parameter names to the description above. In cases where the connection is clear enough, these sections are allowed to be omitted.

pkg.odin-lang.org automatically converts all section names to bold. Therefore putting asterisks manually is not advised. LSP hover providers should take that into account as well.

✅ Inputs:
❌ **Inputs:**
❌ **Inputs**:

The input field must contain a markdown list of parameters. It should be formatted as follows, with backticks surrounding the parameter names (If the parameters are unnamed, names are dropped), and the colon separating the parameter name from its description.

✅
Inputs:
- `x`: The first value
- `y`: The second value

✅
Inputs:
- The first value
- The second value

Exactly the same formatting is expected for the Returns section.

Avoid more than one line per parameter in this section, and also avoid too many references to parameters, when not required:

❌ How NOT to

/*
Round a duration to a specific unit

This procedure rounds the duration `d` to a specific unit `m`

Inputs:
- `d`: The duration to round
- `m`: The unit to round to
  Any `Duration` value can also be supplied as a Unit.

Returns:
- The duration `d` rounded to `m`
*/
duration_round :: proc "contextless" (d, m: Duration) -> Duration

✅ How TO

/*
Round a duration to a specific unit

This procedure rounds the duration `d` to a specific unit `m`

**Note**: Any `Duration` value can also be supplied as a Unit.

**Inputs**:
- `d`: The duration to round
- `m`: The unit to round to

**Returns**:
- The rounded duration
*/
duration_round :: proc "contextless" (d, m: Duration) -> Duration

Note that this effectively spells the same thing twice -- once in the full description, and once more in the inputs/returns sections. This is on purpose. The information is duplicated to allow quick scanning of documentation to obtain the information in whatever format you need -- if you need a quick reference, the user will quickly scan for Inputs/Returns sections. If more detail is needed, they would carefully read the full description. Therefore the full description should also mention the fields by name.

4. Examples and Output sections

These section are optional, but strongly advised. These two sections always come in pairs.

The Examples section must contain executable source code inside a code block. The code must be a valid Odin file (aside from it not needing a package declaration, and some imports). The code must contain a function named <something>_example.

TODO: Resolve what is allowed

The code block must be formatted as an indented string (the tools should correctly deduce the type of code as .odin)

✅ Example

/*
**Examples**:

    import "core:time"
    import "core:fmt"

    // Rounding a duration to seconds
    round_to_unix_seconds_example :: proc() {
        now := Duration(1744710727_657123456) // Unix nanoseconds
        rounded_to_seconds := time.duration_round(now, time.Second)
        fmt.println(rounded_to_seconds)
    }

**Output**:

    1744710727
*/

It is also advised to use real examples of how you might use the procedure, and giving variable's "very descriptive" names.

Do not spam examples to test the edge cases. Examples are not a way to test the procedure, it's the opposite, we test the examples to make sure they run and describe what's gonna happen correctly. For most procedures one is enough. For some 2-3 would suffice.

If the code is not meant to be tested (for example if it has a potential to hang the CI) then _example suffix can be dropped, and the output section in this case becomes optional.

✅ Example

/*
**Example**:

    import "core:sync"

    process_data_multithreaded :: proc(shared_data: ^Data) -> int {
        // 1. Only one thread can proceed after this line.
        sync.mutex_lock(shared_data.mutex)

        // Careful: If both threads touch the shared data
        // it might become corrupted!
        result := process(shared_data)

        // 2. Now the other threads can go into block (1)
        sync.mutex_unlock(shared_data.mutex)

        // We're safe to return what we got as it's not shared.
        return result
    }
*/
mutex_lock :: proc "contextless" (m: ^Mutex)

These rules have a two-fold purpose:

• Allowing the example to be copy-pasted into anywhere
• Allowing the documentation tester to automatically execute and check your examples

5. Other possible sections

• Operation - used for core:simd to explain the array logic in plain-old-loops using pseudocode.
• Thread-safety - might be used to discuss function's ability to alter global state (any other shared state is on the user)
• Errors - can be used to describe conditions for emitting various Errors.

Other sections can be used for packages if they require it. The choice for naming and conventions has to be consistent though.

When introducing a new section, make sure it doesn't belong to the full description instead. The purpose of sections is to provide an information that is uniform across all procedures/types of a package to allow reader to quickly scan the information. An example of a section might be the performance characteristics for data structures. An example of non-section would be Notes, because there's no reason for anyone to try and "quickly find Notes".

6. Notes

When formatting a note you can parenthesize its scope. For example, to Note something for windows implementation you can use:

**Note(windows)**: On windows the behaviour is kinda wonky as always
**Note(linux)**: Linux has something special you might want to consider

III. Formatting guidelines

• Format lists with -
• Format code blocks with tabbed text.
• Don't use markdown images (If possible use ASCII art)
• Bold with **, italic with *
• Escape all references to Inputs and Returns of the function with backticks
• Tables are OK, but don't play around with pipes ('|') inside table cells. Markdown parsers are pretty inconsistent about their escaping.
• Do NOT use HTML inside documentation. < and > should be escaped to < and &gt by the parsers.
• Format links like this: [[ Example; https://example.com/ ]], or [[ https://example.com ]]

IV. General guidelines

Make sure your documentation includes:

• What the thing is
• What the thing does
• Why you might want to use it
• How to use it
• Pitfalls, synchronization considerations, lifetimes, etc. (if applicable)

For the package documentation: it should give an overview of what the package is about, define field-specific terminology, and so on.

Make sure you form your sentences using the proper grammar (capitalize words, end with period, some crap about oxford commas). Try to use simple words, and avoid terminology. Some package-specific terms (like critical section in core:sync, or lifetime in core:mem) should be described in the documentation for the package.

Make sure the full description properly references inputs and returns from the respective sections and the names of the variables match the function signature.

[Sojamann]

A very nice write up <3.

My 4,5 cents on this:

I.2

I feel like it should be the other way around. The procedure group wait in core/sync is a good example. All the procedures basically say, “Let’s wait for something,” but the specifics differ between each one. Since more documentation—especially detailed documentation—is generally a good thing, I’d say this extra bit of “copy and pasting” is actually a good fit for something as central as core, right?

II.2

II.2 Since many procedures are already well-named and self-explanatory, a full description can be considered optional—though, as with the examples, it's still encouraged.

[flysand7]

Regarding copy-pasting, yes, I consider copy-pasting documentation to not be a bad thing. sync.wait has specifics for each type, whereas something like math.sin differs in the type only and there are no specifics between the types.

This is why I initially suggested this should be done depending on the case. Which I'm realizing, does hurt consistency somewhat. I'll try thinking about it.

As for the full description - great suggestion. Though I do feel like there's a leeway for assuming that something is "obvious" when in fact it lacks context for understanding why its obvious. But otherwise I do agree -- some procedures don't need a full descriptions if it can be described fully with a short description and have no "gotchas"

[laytan]

Great, some notes:

1. I personally don't like adding ** for the conventional Returns: and Inputs:, I see the reason is an LSP, but an LSP can process and make it bold just as we do in the documentation generator script. I find it's a bit messy. It's already on a line by itself, and easy to scan for as is. We should not pamper to what the LSP currently does.
2. Italics are done with a single *, not with _ (source: https://github.com/odin-lang/pkg.odin-lang.org?tab=readme-ov-file#inline)
3. Should prob mention in addition to formatting lists with -, they should not be indented, afaik that f's up the generator
4. "Non-Odin code should go in triple backticks" -> That will fk with the generator too, should just be indented with tabs
5. I would mention that package docs need to be attached to the package blah statement to actually be package docs
6. I would like to see a guideline on usage of backticks around variable, procedure or other things, when to do it, when not to do it, I don't have an opinion but we should try to be consistent there too
7. You called a heading "Markdown usage" but we don't actually use markdown
8. Mention how to format links: [[ Example; https://example.com/ ]], or [[ https://example.com ]]
9. We shouldn't require inputs and return sections

[flysand7]

Ah! Right. I'll fix it later today. Is there a name for the format that we use (the one that's Not Markdown)?

[flysand7]

Thanks for the input. I have updated this discussion to reflect on the changes, there are a few more questions to clear up.

First, I would like you to read this. Do we want to follow this? Aside from the benefits to it as for writing skills, there's also one other benefit we could have from it -- cleaner diffs. This, combined with making 120 character limit could be readable in plaintext, and push documentation contributors to try their best at writing shorter, more concise sentences that flow naturally.

The second thing that I have a problem with is the format of the first sentence of the full description. Does it need to start with "This procedure ..."? Or is there a better way?

Compute sin

Computes the sin of x

Might not be too bad?

[flysand7]

Regarding "This procedure", I just happened to look at what git generates as the commit message when reverting a commit via git revert, and I think I've found the solution to my problem.

commit 91568df3db41b6503c80a293eec60e21636bca15 (HEAD -> main)
Author: flysand7 <[email protected]>
Date:   Sat Apr 26 11:42:45 2025 +1100

    Revert "Add postgres database into the container"
    
    This reverts commit 4a348fcb214521e76fc871af8bc5a756d986bcac.

Instead of saying "this commit" it simply states "this does X". So If I translate this to a sample documentation comment, it would look something like:

/*
Round a duration to a specific unit

This rounds the duration `d` to a specific unit `m`
*/
duration_round :: proc "contextless" (d, m: Duration) -> Duration

How does it look? I know @laytan had some issues with "this procedure" prefix, do you think this makes it any better?

---

Regarding my work on the documentation front, I've just moved out, and it's gonna take a while until I get my desk, keyboard and everything else. I will probably continue after a few weeks.

[CortexReaver]

Hm, this is what concerns me the most. Odin in general needs more guides. I mean ANY guides. It is very cool language that "feels right" with a lot of out of the box comfort, but the lack of tutorials might kill it.
Tutorials might be not that important for experienced coders, but they are essential for any new user.
Someone, may be a even GB himself, should take time to write a complete guide with step by step examples for the language. Look at "Official Nim tutorial" in 3 parts for example: https://nim-lang.org/docs/tut1.html Hell, even Zig right now has two (free !) books already!
With Odin you have to scavenge little by little videos on yt and prey to all gods that the author will not drop it after two weeks.

[sz-piotr]

There is https://github.com/odin-lang/examples as well as https://github.com/odin-lang/Odin/blob/master/examples/demo/demo.odin

But I agree that despite those resources odin feels lacking. Maybe it's because discovering those two took me some time?

[CortexReaver]

These are not guides. Look at Nim tutorial I've used as an example.
Also https://github.com/Capati/odin-vk-guide - THIS is a guide. Even a toddler can learn from it, because every step is explained. Code with comments shouldn't be considered a tutorial. Yes, it can be helpful when you stuck at some point and you need alternative point of view, but this is not very beginner friendly.

[sz-piotr]

Hi. For 3. Inputs and Returns the two examples given are inconsistent. The first says it should be Inputs: while the second shows us **Inputs**:

[flysand7]

Thanks for catching, there was a change. I'll fix that

[sz-piotr]

What about:

**Examples**:
**Output**:

in section 4, and

**Note(windows)**:
**Note(linux)**:

in section 6?

[flysand7]

Notes are not sections -- these are specially marked bits of information, but still are a part of the entity's description. Perhaps I should make that clear somewhere

[laytan]

How does it look? I know @laytan had some issues with "this procedure" prefix, do you think this makes it any better?

I think that's great 👍

[flysand7]

Here's an interesting thought I had. If you copy-paste documentation (as opposed to saying "see procedure/type X documentation"), you can delete any functions without worrying about updating documentation of other similar procedures. Of course this can't be applied generally, because there are other legitimate reasons to cross-reference documentation, but it does give you a slight advantage when developing a highly volatile package.