string code docs

core/strings/intern.odin

@@ -2,49 +2,96 @@ package strings
 
 import "core:runtime"
 
-// custom string entry struct
+// Custom string entry struct
 Intern_Entry :: struct {
 	len:  int,
 	str:  [1]byte, // string is allocated inline with the entry to keep allocations simple
 }
+/*
+Intern is a more memory efficient string map
 
-// "intern" is a more memory efficient string map
-// `allocator` is used to allocate the actual `Intern_Entry` strings
+Uses Specified Allocator for `Intern_Entry` strings
+
+Fields:
+- allocator: The allocator used for the Intern_Entry strings
+- entries: A map of strings to interned string entries
+*/
 Intern :: struct {
 	allocator: runtime.Allocator,
 	entries: map[string]^Intern_Entry,
 }
+/*
+Initializes the entries map and sets the allocator for the string entries
 
-// initialize the entries map and set the allocator for the string entries
+*Allocates Using Provided Allocators*
+
+Inputs:
+- m: A pointer to the Intern struct to be initialized
+- allocator: The allocator for the Intern_Entry strings (Default: context.allocator)
+- map_allocator: The allocator for the map of entries (Default: context.allocator)
+*/
 intern_init :: proc(m: ^Intern, allocator := context.allocator, map_allocator := context.allocator) {
 	m.allocator = allocator
 	m.entries = make(map[string]^Intern_Entry, 16, map_allocator)
 }
+/*
+Frees the map and all its content allocated using the `.allocator`.
 
-// free the map and all its content allocated using the `.allocator`
+Inputs:
+- m: A pointer to the Intern struct to be destroyed
+*/
 intern_destroy :: proc(m: ^Intern) {
 	for _, value in m.entries {
 		free(value, m.allocator)
 	}
 	delete(m.entries)
 }
+/*
+Returns the interned string for the given text, is set in the map if it didnt exist yet.
 
-// returns the `text` string from the intern map - gets set if it didnt exist yet
-// the returned string lives as long as the map entry lives
+*MAY Allocate using the Intern's Allocator*
+
+Inputs:
+- m: A pointer to the Intern struct
+- text: The string to be interned
+
+NOTE: The returned string lives as long as the map entry lives.
+
+Returns: The interned string and an allocator error if any
+*/
 intern_get :: proc(m: ^Intern, text: string) -> (str: string, err: runtime.Allocator_Error) {
 	entry := _intern_get_entry(m, text) or_return
 	#no_bounds_check return string(entry.str[:entry.len]), nil
 }
+/*
+Returns the interned C-String for the given text, is set in the map if it didnt exist yet.
 
-// returns the `text` cstring from the intern map - gets set if it didnt exist yet
-// the returned cstring lives as long as the map entry lives
+*MAY Allocate using the Intern's Allocator*
+
+Inputs:
+- m: A pointer to the Intern struct
+- text: The string to be interned
+
+NOTE: The returned C-String lives as long as the map entry lives
+
+Returns: The interned C-String and an allocator error if any
+*/
 intern_get_cstring :: proc(m: ^Intern, text: string) -> (str: cstring, err: runtime.Allocator_Error) {
 	entry := _intern_get_entry(m, text) or_return
 	return cstring(&entry.str[0]), nil
 }
+/*
+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
 
-// looks up wether the `text` string exists in the map, returns the entry
-// sets & allocates the entry if it wasnt set yet
+*MAY Allocate using the Intern's Allocator*
+
+Inputs:
+- m: A pointer to the Intern struct
+- text: The string to be looked up or interned
+
+Returns: The new or existing interned entry and an allocator error if any
+*/
 _intern_get_entry :: proc(m: ^Intern, text: string) -> (new_entry: ^Intern_Entry, err: runtime.Allocator_Error) #no_bounds_check {
 	if prev, ok := m.entries[text]; ok {
 		return prev, nil