toml: update value_opt syntax and add missing documentation (#16510)

vlib/toml/README.md

@@ -80,7 +80,7 @@ can use the `.default_to(...)` function to provide a
 default value.
 
 For cases where a default value might not be appropiate or
-to check if a value exists you can use `doc.value_opt('query')?`
+to check if a value exists you can use `doc.value_opt('query')!`
 instead.
 
 ```v

vlib/toml/any.v

@@ -285,7 +285,9 @@ pub fn (a Any) value(key string) Any {
 	return a.value_(a, key_split)
 }
 
-pub fn (a Any) value_opt(key string) ?Any {
+// value_opt queries a value from the current element's tree. Returns an error
+// if the key is not valid or there is no value for the key.
+pub fn (a Any) value_opt(key string) !Any {
 	key_split := parse_dotted_key(key) or { return error('invalid dotted key') }
 	x := a.value_(a, key_split)
 	if x is Null {

vlib/toml/ast/ast.v

@@ -16,6 +16,7 @@ pub mut:
 	// errors           []errors.Error    // all the checker errors in the file
 }
 
+// str returns the string representation of the root node.
 pub fn (r Root) str() string {
 	mut s := typeof(r).name + '{\n'
 	s += '  input:  ${r.input}\n'

vlib/toml/ast/types.v

@@ -10,6 +10,8 @@ import strconv
 // can be found in a TOML document.
 pub type Key = Bare | Bool | Null | Number | Quoted
 
+// str returns the string representation of the key. This is implemented
+// by all the variants of Key.
 pub fn (k Key) str() string {
 	return k.text
 }

vlib/toml/ast/walker/walker.v

@@ -20,6 +20,7 @@ mut:
 	data voidptr
 }
 
+// visit calls the inspector callback on the specified Value node.
 pub fn (i &Inspector) visit(value &ast.Value) ! {
 	i.inspector_callback(value, i.data) or { return err }
 }

vlib/toml/parser/parser.v

@@ -19,6 +19,7 @@ pub const (
 
 type DottedKey = []string
 
+// str returns the dotted key as a string.
 pub fn (dk DottedKey) str() string {
 	return dk.join('.')
 }

vlib/toml/token/token.v

@@ -41,6 +41,7 @@ pub enum Kind {
 	_end_
 }
 
+// pos returns the exact position of a token in the input.
 [inline]
 pub fn (tok &Token) pos() Pos {
 	return Pos{

vlib/toml/toml.v

@@ -31,6 +31,7 @@ pub struct DateTime {
 	datetime string
 }
 
+// str returns the RFC 3339 string representation of the datetime.
 pub fn (dt DateTime) str() string {
 	return dt.datetime
 }
@@ -40,6 +41,7 @@ pub struct Date {
 	date string
 }
 
+// str returns the RFC 3339 date-only string representation.
 pub fn (d Date) str() string {
 	return d.date
 }
@@ -49,6 +51,7 @@ pub struct Time {
 	time string
 }
 
+// str returns the RFC 3339 time-only string representation.
 pub fn (t Time) str() string {
 	return t.time
 }
@@ -207,6 +210,8 @@ pub fn (d Doc) value(key string) Any {
 
 pub const null = Any(Null{})
 
+// value_opt queries a value from the TOML document. Returns an error if the
+// key is not valid or there is no value for the key.
 pub fn (d Doc) value_opt(key string) !Any {
 	key_split := parse_dotted_key(key) or { return error('invalid dotted key') }
 	x := d.value_(d.ast.table, key_split)

vlib/toml/util/util.v

@@ -3,6 +3,7 @@
 // that can be found in the LICENSE file.
 module util
 
+// is_key_char returns true if the given u8 is a valid key character.
 [inline]
 pub fn is_key_char(c u8) bool {
 	return (c >= `a` && c <= `z`) || (c >= `A` && c <= `Z`) // || c == `_`  || c == `-` <- these are identified when tokenizing
@@ -21,6 +22,8 @@ pub fn is_illegal_ascii_control_character(byte_char u8) bool {
 	return byte_char != 0x09 && is_ascii_control_character(byte_char)
 }
 
+// printdbg is a utility function for displaying a key:pair error message
+// when `-d trace_toml` is passed to the compiler.
 [if trace_toml ?]
 pub fn printdbg(id string, message string) {
 	eprintln(id + ' ' + message)