Small improvements strings documentation

* Use new 'Returns:' and 'Inputs:' keywords used by the website generator
* Make order item order resemble website, i.e. 'Returns:' comes before
  'Example:'
* Add a few missing input items
* Add a few missing return items

core/strings/builder.odin

@@ -7,10 +7,10 @@ import "core:io"
 /*
 Type definition for a procedure that flushes a Builder
 
-**Inputs**  
+Inputs:
 - b: A pointer to the Builder
 
-**Returns**  
+Returns:
 A boolean indicating whether the Builder should be reset
 */
 Builder_Flush_Proc :: #type proc(b: ^Builder) -> (do_reset: bool)
@@ -27,10 +27,10 @@ Produces a Builder with a default length of 0 and cap of 16
 
 *Allocates Using Provided Allocator*
 
-**Inputs**  
+Inputs:
 - allocator: (default is context.allocator)
 
-**Returns**  
+Returns:
 A new Builder
 */
 builder_make_none :: proc(allocator := context.allocator) -> Builder {
@@ -41,11 +41,11 @@ Produces a Builder with a specified length and cap of max(16,len) byte buffer
 
 *Allocates Using Provided Allocator*
 
-**Inputs**  
+Inputs:
 - len: The desired length of the Builder's buffer
 - allocator: (default is context.allocator)
 
-**Returns**  
+Returns:
 A new Builder
 */
 builder_make_len :: proc(len: int, allocator := context.allocator) -> Builder {
@@ -56,12 +56,12 @@ Produces a Builder with a specified length and cap
 
 *Allocates Using Provided Allocator*
 
-**Inputs**  
+Inputs:
 - len: The desired length of the Builder's buffer
 - cap: The desired capacity of the Builder's buffer, cap is max(cap, len)
 - allocator: (default is context.allocator)
 
-**Returns**  
+Returns:
 A new Builder
 */
 builder_make_len_cap :: proc(len, cap: int, allocator := context.allocator) -> Builder {
@@ -79,11 +79,11 @@ It replaces the existing `buf`
 
 *Allocates Using Provided Allocator*
 
-**Inputs**  
+Inputs:
 - b: A pointer to the Builder
 - allocator: (default is context.allocator)
 
-**Returns**  
+Returns:
 initialized ^Builder
 */
 builder_init_none :: proc(b: ^Builder, allocator := context.allocator) -> ^Builder {
@@ -96,12 +96,12 @@ It replaces the existing `buf`
 
 *Allocates Using Provided Allocator*
 
-**Inputs**  
+Inputs:
 - b: A pointer to the Builder
 - len: The desired length of the Builder's buffer
 - allocator: (default is context.allocator)
 
-**Returns**  
+Returns:
 Initialized ^Builder
 */
 builder_init_len :: proc(b: ^Builder, len: int, allocator := context.allocator) -> ^Builder {
@@ -112,13 +112,13 @@ builder_init_len :: proc(b: ^Builder, len: int, allocator := context.allocator)
 Initializes a Builder with a specified length and cap
 It replaces the existing `buf`
 
-**Inputs**  
+Inputs:
 - b: A pointer to the Builder
 - len: The desired length of the Builder's buffer
 - cap: The desired capacity of the Builder's buffer, actual max(len,cap)
 - allocator: (default is context.allocator)
 
-**Returns**  
+Returns:
 A pointer to the initialized Builder
 */
 builder_init_len_cap :: proc(b: ^Builder, len, cap: int, allocator := context.allocator) -> ^Builder {
@@ -165,10 +165,10 @@ _builder_stream_vtable := &_builder_stream_vtable_obj
 /*
 Returns an io.Stream from a Builder
 
-**Inputs**  
+Inputs:
 - b: A pointer to the Builder
 
-**Returns**  
+Returns:
 An io.Stream
 */
 to_stream :: proc(b: ^Builder) -> io.Stream {
@@ -177,10 +177,10 @@ to_stream :: proc(b: ^Builder) -> io.Stream {
 /*
 Returns an io.Writer from a Builder
 
-**Inputs**  
+Inputs:
 - b: A pointer to the Builder
 
-**Returns**   
+Returns: 
 An io.Writer
 */
 to_writer :: proc(b: ^Builder) -> io.Writer {
@@ -189,7 +189,7 @@ to_writer :: proc(b: ^Builder) -> io.Writer {
 /*
 Deletes the Builder byte buffer content
 
-**Inputs**  
+Inputs:
 - b: A pointer to the Builder
 */
 builder_destroy :: proc(b: ^Builder) {
@@ -199,7 +199,7 @@ builder_destroy :: proc(b: ^Builder) {
 /*
 Reserves the Builder byte buffer to a specific capacity, when it's higher than before
 
-**Inputs**  
+Inputs:
 - b: A pointer to the Builder
 - cap: The desired capacity for the Builder's buffer
 */
@@ -209,7 +209,7 @@ builder_grow :: proc(b: ^Builder, cap: int) {
 /*
 Clears the Builder byte buffer content (sets len to zero)
 
-**Inputs**  
+Inputs:
 - b: A pointer to the Builder
 */
 builder_reset :: proc(b: ^Builder) {
@@ -220,9 +220,12 @@ Creates a Builder from a slice of bytes with the same slice length as its capaci
 
 *Uses Nil Allocator - Does NOT allocate*
 
-**Inputs**  
+Inputs:
 - backing: A slice of bytes to be used as the backing buffer
 
+Returns:
+A new Builder
+
 Example:
 
 	import "core:fmt"
@@ -241,8 +244,6 @@ Output:
 	a
 	ab
 
-**Returns**  
-A new Builder
 */
 builder_from_bytes :: proc(backing: []byte) -> Builder {
 	s := transmute(runtime.Raw_Slice)backing
@@ -261,10 +262,10 @@ builder_from_slice :: builder_from_bytes
 /*
 Casts the Builder byte buffer to a string and returns it
 
-**Inputs**  
+Inputs:
 - b: A Builder
 
-**Returns**  
+Returns:
 The contents of the Builder's buffer, as a string
 */
 to_string :: proc(b: Builder) -> string {
@@ -273,10 +274,10 @@ to_string :: proc(b: Builder) -> string {
 /*
 Returns the length of the Builder's buffer, in bytes
 
-**Inputs**  
+Inputs:
 - b: A Builder
 
-**Returns**  
+Returns:
 The length of the Builder's buffer
 */
 builder_len :: proc(b: Builder) -> int {
@@ -285,10 +286,10 @@ builder_len :: proc(b: Builder) -> int {
 /*
 Returns the capacity of the Builder's buffer, in bytes
 
-**Inputs**  
+Inputs:
 - b: A Builder
 
-**Returns**  
+Returns:
 The capacity of the Builder's buffer
 */
 builder_cap :: proc(b: Builder) -> int {
@@ -297,10 +298,10 @@ builder_cap :: proc(b: Builder) -> int {
 /*
 The free space left in the Builder's buffer, in bytes
 
-**Inputs**  
+Inputs:
 - b: A Builder
 
-**Returns**  
+Returns:
 The available space left in the Builder's buffer
 */
 builder_space :: proc(b: Builder) -> int {
@@ -309,10 +310,15 @@ builder_space :: proc(b: Builder) -> int {
 /*
 Appends a byte to the Builder and returns the number of bytes appended
 
-**Inputs**  
+Inputs:
 - b: A pointer to the Builder
 - x: The byte to be appended
 
+Returns:
+The number of bytes appended
+
+NOTE: The backing dynamic array may be fixed in capacity or fail to resize, `n` states the number actually written.
+
 Example:
 
 	import "core:fmt"
@@ -329,10 +335,6 @@ Output:
 
 	ab
 
-NOTE: The backing dynamic array may be fixed in capacity or fail to resize, `n` states the number actually written.
-
-**Returns**  
-The number of bytes appended
 */
 write_byte :: proc(b: ^Builder, x: byte) -> (n: int) {
 	n0 := len(b.buf)
@@ -343,7 +345,7 @@ write_byte :: proc(b: ^Builder, x: byte) -> (n: int) {
 /*
 Appends a slice of bytes to the Builder and returns the number of bytes appended
 
-**Inputs**  
+Inputs:
 - b: A pointer to the Builder
 - x: The slice of bytes to be appended
 
@@ -361,7 +363,7 @@ Example:
 
 NOTE: The backing dynamic array may be fixed in capacity or fail to resize, `n` states the number actually written.
 
-**Returns**  
+Returns:
 The number of bytes appended
 */
 write_bytes :: proc(b: ^Builder, x: []byte) -> (n: int) {
@@ -373,10 +375,15 @@ write_bytes :: proc(b: ^Builder, x: []byte) -> (n: int) {
 /*
 Appends a single rune to the Builder and returns the number of bytes written and an `io.Error`
 
-**Inputs**  
+Inputs:
 - b: A pointer to the Builder
 - r: The rune to be appended
 
+Returns:
+The number of bytes written and an io.Error (if any)
+
+NOTE: The backing dynamic array may be fixed in capacity or fail to resize, `n` states the number actually written.
+
 Example:
 
 	import "core:fmt"
@@ -393,10 +400,6 @@ Output:
 
 	äb
 
-NOTE: The backing dynamic array may be fixed in capacity or fail to resize, `n` states the number actually written.
-
-**Returns**  
-The number of bytes written and an io.Error (if any)
 */
 write_rune :: proc(b: ^Builder, r: rune) -> (int, io.Error) {
 	return io.write_rune(to_writer(b), r)
@@ -404,10 +407,15 @@ write_rune :: proc(b: ^Builder, r: rune) -> (int, io.Error) {
 /*
 Appends a quoted rune to the Builder and returns the number of bytes written
 
-**Inputs**  
+Inputs:
 - b: A pointer to the Builder
 - r: The rune to be appended
 
+Returns:
+The number of bytes written
+
+NOTE: The backing dynamic array may be fixed in capacity or fail to resize, `n` states the number actually written.
+
 Example:
 
 	import "core:fmt"
@@ -425,10 +433,6 @@ Output:
 
 	abc'ä'abc
 
-NOTE: The backing dynamic array may be fixed in capacity or fail to resize, `n` states the number actually written.
-
-**Returns**  
-The number of bytes written
 */
 write_quoted_rune :: proc(b: ^Builder, r: rune) -> (n: int) {
 	return io.write_quoted_rune(to_writer(b), r)
@@ -436,10 +440,15 @@ write_quoted_rune :: proc(b: ^Builder, r: rune) -> (n: int) {
 /*
 Appends a string to the Builder and returns the number of bytes written
 
-**Inputs**  
+Inputs:
 - b: A pointer to the Builder
 - s: The string to be appended
 
+Returns:
+The number of bytes written
+
+NOTE: The backing dynamic array may be fixed in capacity or fail to resize, `n` states the number actually written.
+
 Example:
 
 	import "core:fmt"
@@ -456,10 +465,6 @@ Output:
 
 	abc
 
-NOTE: The backing dynamic array may be fixed in capacity or fail to resize, `n` states the number actually written.
-
-**Returns**  
-The number of bytes written
 */
 write_string :: proc(b: ^Builder, s: string) -> (n: int) {
 	n0 := len(b.buf)
@@ -470,10 +475,10 @@ write_string :: proc(b: ^Builder, s: string) -> (n: int) {
 /*
 Pops and returns the last byte in the Builder or 0 when the Builder is empty
 
-**Inputs**  
+Inputs:
 - b: A pointer to the Builder
 
-**Returns**  
+Returns:
 The last byte in the Builder or 0 if empty
 */
 pop_byte :: proc(b: ^Builder) -> (r: byte) {
@@ -489,10 +494,10 @@ pop_byte :: proc(b: ^Builder) -> (r: byte) {
 /*
 Pops the last rune in the Builder and returns the popped rune and its rune width or (0, 0) if empty
 
-**Inputs**  
+Inputs:
 - b: A pointer to the Builder
 
-**Returns**  
+Returns:
 The popped rune and its rune width or (0, 0) if empty
 */
 pop_rune :: proc(b: ^Builder) -> (r: rune, width: int) {
@@ -508,11 +513,16 @@ pop_rune :: proc(b: ^Builder) -> (r: rune, width: int) {
 @(private)
 DIGITS_LOWER := "0123456789abcdefx"
 /*
-**Inputs**  
+Inputs:
 - b: A pointer to the Builder
 - str: The string to be quoted and appended
 - quote: The optional quote character (default is double quotes)
 
+Returns:
+The number of bytes written
+
+NOTE: The backing dynamic array may be fixed in capacity or fail to resize, `n` states the number actually written.
+
 Example:
 
 	import "core:fmt"
@@ -530,10 +540,6 @@ Output:
 
 	"a"'bc'"xyz"
 
-NOTE: The backing dynamic array may be fixed in capacity or fail to resize, `n` states the number actually written.
-
-**Returns**  
-The number of bytes written
 */
 write_quoted_string :: proc(b: ^Builder, str: string, quote: byte = '"') -> (n: int) {
 	n, _ = io.write_quoted_string(to_writer(b), str, quote)
@@ -542,11 +548,16 @@ write_quoted_string :: proc(b: ^Builder, str: string, quote: byte = '"') -> (n:
 /*
 Appends a rune to the Builder and returns the number of bytes written
 
-**Inputs**  
+Inputs:
 - b: A pointer to the Builder
 - r: The rune to be appended
 - write_quote: Optional boolean flag to wrap in single-quotes (') (default is true)
 
+Returns:
+The number of bytes written
+
+NOTE: The backing dynamic array may be fixed in capacity or fail to resize, `n` states the number actually written.
+
 Example:
 
 	import "core:fmt"
@@ -564,10 +575,6 @@ Output:
 
 	a'"'x
 
-NOTE: The backing dynamic array may be fixed in capacity or fail to resize, `n` states the number actually written.
-
-**Returns**  
-The number of bytes written
 */
 write_encoded_rune :: proc(b: ^Builder, r: rune, write_quote := true) -> (n: int) {
 	n, _ = io.write_encoded_rune(to_writer(b), r, write_quote)
@@ -577,7 +584,7 @@ write_encoded_rune :: proc(b: ^Builder, r: rune, write_quote := true) -> (n: int
 /*
 Appends an escaped rune to the Builder and returns the number of bytes written
 
-**Inputs**  
+Inputs:
 - b: A pointer to the Builder
 - r: The rune to be appended
 - quote: The quote character
@@ -590,7 +597,7 @@ Appends an escaped rune to the Builder and returns the number of bytes written
 
 NOTE: The backing dynamic array may be fixed in capacity or fail to resize, `n` states the number actually written.
 
-**Returns**  
+Returns:
 The number of bytes written
 */
 write_escaped_rune :: proc(b: ^Builder, r: rune, quote: byte, html_safe := false) -> (n: int) {
@@ -600,7 +607,7 @@ write_escaped_rune :: proc(b: ^Builder, r: rune, quote: byte, html_safe := false
 /*
 Writes a f64 value to the Builder and returns the number of characters written
 
-**Inputs**  
+Inputs:
 - b: A pointer to the Builder
 - f: The f64 value to be appended
 - fmt: The format byte
@@ -610,7 +617,7 @@ Writes a f64 value to the Builder and returns the number of characters written
 
 NOTE: The backing dynamic array may be fixed in capacity or fail to resize, `n` states the number actually written.
 
-**Returns**  
+Returns:
 The number of characters written
 */
 write_float :: proc(b: ^Builder, f: f64, fmt: byte, prec, bit_size: int, always_signed := false) -> (n: int) {
@@ -626,7 +633,7 @@ write_float :: proc(b: ^Builder, f: f64, fmt: byte, prec, bit_size: int, always_
 /*
 Writes a f16 value to the Builder and returns the number of characters written
 
-**Inputs**  
+Inputs:
 - b: A pointer to the Builder
 - f: The f16 value to be appended
 - fmt: The format byte
@@ -634,7 +641,7 @@ Writes a f16 value to the Builder and returns the number of characters written
 
 NOTE: The backing dynamic array may be fixed in capacity or fail to resize, `n` states the number actually written.
 
-**Returns**  
+Returns:
 The number of characters written
 */
 write_f16 :: proc(b: ^Builder, f: f16, fmt: byte, always_signed := false) -> (n: int) {
@@ -648,12 +655,17 @@ write_f16 :: proc(b: ^Builder, f: f16, fmt: byte, always_signed := false) -> (n:
 /*
 Writes a f32 value to the Builder and returns the number of characters written
 
-**Inputs**  
+Inputs:
 - b: A pointer to the Builder
 - f: The f32 value to be appended
 - fmt: The format byte
 - always_signed: Optional boolean flag to always include the sign
 
+Returns:
+The number of characters written
+
+NOTE: The backing dynamic array may be fixed in capacity or fail to resize, `n` states the number actually written.
+
 Example:
 
 	import "core:fmt"
@@ -671,10 +683,6 @@ Output:
 
 	3.14159012 - -1.23000003e-01
 
-NOTE: The backing dynamic array may be fixed in capacity or fail to resize, `n` states the number actually written.
-
-**Returns**  
-The number of characters written
 */
 write_f32 :: proc(b: ^Builder, f: f32, fmt: byte, always_signed := false) -> (n: int) {
 	buf: [384]byte
@@ -687,7 +695,7 @@ write_f32 :: proc(b: ^Builder, f: f32, fmt: byte, always_signed := false) -> (n:
 /*
 Writes a f32 value to the Builder and returns the number of characters written
 
-**Inputs**  
+Inputs:
 - b: A pointer to the Builder
 - f: The f32 value to be appended
 - fmt: The format byte
@@ -695,7 +703,7 @@ Writes a f32 value to the Builder and returns the number of characters written
 
 NOTE: The backing dynamic array may be fixed in capacity or fail to resize, `n` states the number actually written.
 
-**Returns**  
+Returns:
 The number of characters written
 */
 write_f64 :: proc(b: ^Builder, f: f64, fmt: byte, always_signed := false) -> (n: int) {
@@ -709,14 +717,14 @@ write_f64 :: proc(b: ^Builder, f: f64, fmt: byte, always_signed := false) -> (n:
 /*
 Writes a u64 value to the Builder and returns the number of characters written
 
-**Inputs**  
+Inputs:
 - b: A pointer to the Builder
 - i: The u64 value to be appended
 - base: The optional base for the numeric representation
 
 NOTE: The backing dynamic array may be fixed in capacity or fail to resize, `n` states the number actually written.
 
-**Returns**  
+Returns:
 The number of characters written
 */
 write_u64 :: proc(b: ^Builder, i: u64, base: int = 10) -> (n: int) {
@@ -727,14 +735,14 @@ write_u64 :: proc(b: ^Builder, i: u64, base: int = 10) -> (n: int) {
 /*
 Writes a i64 value to the Builder and returns the number of characters written
 
-**Inputs**  
+Inputs:
 - b: A pointer to the Builder
 - i: The i64 value to be appended
 - base: The optional base for the numeric representation
 
 NOTE: The backing dynamic array may be fixed in capacity or fail to resize, `n` states the number actually written.
 
-**Returns**  
+Returns:
 The number of characters written
 */
 write_i64 :: proc(b: ^Builder, i: i64, base: int = 10) -> (n: int) {
@@ -745,14 +753,14 @@ write_i64 :: proc(b: ^Builder, i: i64, base: int = 10) -> (n: int) {
 /*
 Writes a uint value to the Builder and returns the number of characters written
 
-**Inputs**  
+Inputs:
 - b: A pointer to the Builder
 - i: The uint value to be appended
 - base: The optional base for the numeric representation
 
 NOTE: The backing dynamic array may be fixed in capacity or fail to resize, `n` states the number actually written.
 
-**Returns**  
+Returns:
 The number of characters written
 */
 write_uint :: proc(b: ^Builder, i: uint, base: int = 10) -> (n: int) {
@@ -761,14 +769,14 @@ write_uint :: proc(b: ^Builder, i: uint, base: int = 10) -> (n: int) {
 /*
 Writes a int value to the Builder and returns the number of characters written
 
-**Inputs**  
+Inputs:
 - b: A pointer to the Builder
 - i: The int value to be appended
 - base: The optional base for the numeric representation
 
 NOTE: The backing dynamic array may be fixed in capacity or fail to resize, `n` states the number actually written.
 
-**Returns**  
+Returns:
 The number of characters written
 */
 write_int :: proc(b: ^Builder, i: int, base: int = 10) -> (n: int) {