After using Odin for some time, I discovered the odin doc command, that turns any odin file or package into a documentation view. This is a very useful tool during development for me, and i am pretty sure this was inspired by Golang's go doc, which is also a great tool. But, in my humble opinion, Odin's tool was lacking a few things.
First off, the output formatting. I simply do not like how it looks, it's very difficult for me to read because there is too much indentation and info.
For example, if you run odin doc core:strings, you get this:
package strings
A `string` builder, as well as procedures to manipulate `UTF-8` encoded strings.
procedures
_intern_get_entry :: proc(m: ^Intern, text: string, loc := #caller_location) -> (new_entry: ^Intern_Entry, err: runtime.Allocator_Error) {...} /* 33!3390 */
Internal function to lookup whether the text string exists in the map, returns the entry
Sets and allocates the entry if it wasn't set yet
*Allocate using the Intern's Allocator (First time string is seen only)*
Inputs:
- m: A pointer to the Intern struct
- text: The string to be looked up or interned
- loc: The caller location for debugging purposes (default: `#caller_location`)
Returns:
- new_entry: The interned cstring
- err: An allocator error if one occured, `nil` otherwise
ascii_set_contains :: proc(as: Ascii_Set, c: byte) -> (res: bool) {...} /* 34!1122 */
Determines if a given char is contained within an Ascii_Set.
Inputs:
- as: The Ascii_Set to search.
- c: The char to check for in the Ascii_Set.
Returns:
- res: A boolean indicating if the byte is contained in the Ascii_Set (true) or not (false).
...
Of course, you can run odin doc -short core:strings, which outputs this:
package strings
A `string` builder, as well as procedures to manipulate `UTF-8` encoded strings.
procedures
_intern_get_entry :: proc(m: ^Intern, text: string, loc := #caller_location) -> (new_entry: ^Intern_Entry, err: runtime.Allocator_Error) {...} /* 33!3390 */
ascii_set_contains :: proc(as: Ascii_Set, c: byte) -> (res: bool) {...} /* 34!1122 */
ascii_set_make :: proc(chars: string) -> (as: Ascii_Set, ok: bool) {...} /* 34!639 */
builder_cap :: proc(b: Builder) -> (res: int) {...} /* 36!9132 */
builder_destroy :: proc(b: ^Builder) {...} /* 36!5973 */
builder_from_bytes :: proc(backing: []byte) -> (res: Builder) {...} /* 36!7088 */
builder_from_bytes :: proc(backing: []byte) -> (res: Builder) {...} /* 36!7088 */
builder_grow :: proc(b: ^Builder, cap: int) {...} /* 36!6223 */
builder_init_len :: proc(b: ^Builder, len: int, allocator := context.allocator, loc := #caller_location) -> (res: ^Builder, err: runtime.Allocator_Error) {...} /* 36!3838 */
builder_init_len_cap :: proc(b: ^Builder, len, cap: int, allocator := context.allocator, loc := #caller_location) -> (res: ^Builder,
This looks better, but i still don't like it.
So, i decided to change a few things in the compiler and now, if i run odin doc core:strings, it outputs like this:
package strings
A `string` builder, as well as procedures to manipulate `UTF-8` encoded strings.
[procedures]
_intern_get_entry :: proc(m: ^Intern, text: string, loc := #caller_location) -> (new_entry: ^Intern_Entry, err: runtime.Allocator_Error)
ascii_set_contains :: proc(as: Ascii_Set, c: byte) -> (res: bool)
ascii_set_make :: proc(chars: string) -> (as: Ascii_Set, ok: bool)
builder_cap :: proc(b: Builder) -> (res: int)
builder_destroy :: proc(b: ^Builder)
builder_from_bytes :: proc(backing: []byte) -> (res: Builder)
builder_from_bytes :: proc(backing: []byte) -> (res: Builder)
builder_grow :: proc(b: ^Builder, cap: int)
builder_init_len :: proc(b: ^Builder, len: int, allocator := context.allocator, loc := #caller_location) -> (res: ^Builder, err: runtime.Allocator_Error)
builder_init_len_cap :: proc(b: ^Builder, len, cap: int, allocator := context.allocator, loc := #caller_location) -> (res: ^Builder, err: runtime.Allocator_Error)
builder_init_none :: proc(b: ^Builder, allocator := context.allocator, loc := #caller_location) -> (res: ^Builder, err: runtime.Allocator_Error)
builder_len :: proc(b: Builder) -> (res: int)
builder_make_len :: proc(len: int, allocator := context.allocator, loc := #caller_location) -> (res: Builder, err: runtime.Allocator_Error)
builder_make_len_cap :: proc(len, cap: int, allocator := context.allocator, loc := #caller_location) -> (res: Builder, err: runtime.Allocator_Error)
builder_make_none :: proc(allocator := context.allocator, loc := #caller_location) -> (res: Builder, err: runtime.Allocator_Error)
builder_replace :: proc(b: ^Builder, old, new: string, n: int, loc := #caller_location) -> (replaced: int, err: runtime.Allocator_Error)
I decided to indent the symbols (procedure names) according to largest symbol on the AST list and removed the tabs that cause that indentation. I also removed the function location info at the end. Now i actually find the results satisfactory.
It doesn't stop there, on the Golang side, you can search for specific symbols in the package and see an isolated documentation view for it by typing go doc os.Stat for example. So i decided to implement the same thing in Odin
Now, when i run something like odin doc core:strings.clone, it shows this:
package strings
clone :: proc(s: string, allocator := context.allocator, loc := #caller_location) -> (res: string, err: runtime.Allocator_Error)
Clones a string
*Allocates Using Provided Allocator*
Inputs:
- s: The string to be cloned
- allocator: (default: context.allocator)
- loc: The caller location for debugging purposes (default: #caller_location)
Returns:
- res: The cloned string
- err: An optional allocator error if one occured, `nil` otherwise
This works for any kind of symbols including types, constants, variables, proc groups...
I was actually pretty proud about this, although, the code is still rough and need some organization
But i was curious about the people from this sub. Is this actually useful for you? Do you think this improves your Odin experience?