toml: correct documentation (#11976)

vlib/toml/any.v

@@ -5,7 +5,7 @@ module toml
 
 import time
 
-// Pretty much all json2 types plus time.Time
+// Pretty much all the same builtin types as the `json2.Any` type plus `time.Time`
 pub type Any = Null
 	| []Any
 	| bool

vlib/toml/ast/types.v

@@ -58,12 +58,13 @@ pub fn (v Value) to_json() string {
 // found in a TOML document.
 pub type DateTimeType = Date | DateTime | Time
 
+// str returns the `string` representation of the `DateTimeType` type.
 pub fn (dtt DateTimeType) str() string {
 	return dtt.text
 }
 
 // value queries a value from the map.
-// `key` should be in "dotted" form e.g.: `"a.b.c.d"`
+// `key` should be in "dotted" form (`a.b.c`).
 pub fn (v map[string]Value) value(key string) &Value {
 	null := &Value(Null{})
 	key_split := key.split('.')
@@ -88,7 +89,7 @@ pub fn (v map[string]Value) value(key string) &Value {
 	// TODO return error(@MOD + '.' + @STRUCT + '.' + @FN + ' key "$key" does not exist')
 }
 
-// value queries a value from the map.
+// exists returns true if the "dotted" `key` path exists in the map.
 pub fn (v map[string]Value) exists(key string) bool {
 	key_split := key.split('.')
 	if key_split[0] in v.keys() {
@@ -107,12 +108,14 @@ pub fn (v map[string]Value) exists(key string) bool {
 	return false
 }
 
+// Comment is the data representation of a TOML comment (`# This is a comment`).
 pub struct Comment {
 pub:
 	text string
 	pos  token.Position
 }
 
+// str returns the `string` representation of the `Comment` type.
 pub fn (c Comment) str() string {
 	mut s := typeof(c).name + '{\n'
 	s += '  text:  \'$c.text\'\n'
@@ -128,16 +131,20 @@ pub:
 	pos  token.Position
 }
 
+// str returns the `string` representation of the `Null` type
 pub fn (n Null) str() string {
 	return n.text
 }
 
+// Quoted is the data representation of a TOML quoted type (`"quoted-key" = "I'm a quoted value"`).
+// Quoted types can appear both as keys and values in TOML documents.
 pub struct Quoted {
 pub:
 	text string
 	pos  token.Position
 }
 
+// str returns the `string` representation of the `Quoted` type.
 pub fn (q Quoted) str() string {
 	mut str := typeof(q).name + '{\n'
 	str += '  text:  \'$q.text\'\n'
@@ -146,12 +153,16 @@ pub fn (q Quoted) str() string {
 	return str
 }
 
+// Bare is the data representation of a TOML bare type (`bare_key = ...`).
+// Bare types can appear only as keys in TOML documents. Otherwise they take the
+// form of Bool or Numbers.
 pub struct Bare {
 pub:
 	text string
 	pos  token.Position
 }
 
+// str returns the `string` representation of the `Bare` type.
 pub fn (b Bare) str() string {
 	mut str := typeof(b).name + '{\n'
 	str += '  text:  \'$b.text\'\n'
@@ -160,12 +171,16 @@ pub fn (b Bare) str() string {
 	return str
 }
 
+// Bool is the data representation of a TOML boolean type (`... = true`).
+// Bool types can appear only as values in TOML documents. Keys named `true` or `false`
+// are considered as Bare types.
 pub struct Bool {
 pub:
 	text string
 	pos  token.Position
 }
 
+// str returns the `string` representation of the `Bool` type.
 pub fn (b Bool) str() string {
 	mut str := typeof(b).name + '{\n'
 	str += '  text:  \'$b.text\'\n'
@@ -174,12 +189,16 @@ pub fn (b Bool) str() string {
 	return str
 }
 
+// Number is the data representation of a TOML number type (`25 = 5e2`).
+// Number types can appear both as keys and values in TOML documents.
+// Number can be integers, floats, infinite, NaN - they can have exponents (`5e2`) and be sign prefixed (`+2`).
 pub struct Number {
 pub:
 	text string
 	pos  token.Position
 }
 
+// str returns the `string` representation of the `Number` type.
 pub fn (n Number) str() string {
 	mut str := typeof(n).name + '{\n'
 	str += '  text:  \'$n.text\'\n'
@@ -188,12 +207,16 @@ pub fn (n Number) str() string {
 	return str
 }
 
+// Date is the data representation of a TOML date type (`YYYY-MM-DD`).
+// Date types can appear both as keys and values in TOML documents.
+// Keys named like dates e.g. `1980-12-29` are considered Bare key types.
 pub struct Date {
 pub:
 	text string
 	pos  token.Position
 }
 
+// str returns the `string` representation of the `Date` type.
 pub fn (d Date) str() string {
 	mut str := typeof(d).name + '{\n'
 	str += '  text:  \'$d.text\'\n'
@@ -202,6 +225,8 @@ pub fn (d Date) str() string {
 	return str
 }
 
+// Time is the data representation of a TOML time type (`HH:MM:SS.milli`).
+// Time types can appear only as values in TOML documents.
 pub struct Time {
 pub:
 	text   string
@@ -209,6 +234,7 @@ pub:
 	pos    token.Position
 }
 
+// str returns the `string` representation of the `Time` type.
 pub fn (t Time) str() string {
 	mut str := typeof(t).name + '{\n'
 	str += '  text:  \'$t.text\'\n'
@@ -218,6 +244,8 @@ pub fn (t Time) str() string {
 	return str
 }
 
+// DateTime is the data representation of a TOML date-time type (`YYYY-MM-DDTHH:MM:SS.milli`).
+// DateTime types can appear only as values in TOML documents.
 pub struct DateTime {
 pub:
 	text string
@@ -226,6 +254,7 @@ pub:
 	time Time
 }
 
+// str returns the `string` representation of the `DateTime` type.
 pub fn (dt DateTime) str() string {
 	mut str := typeof(dt).name + '{\n'
 	str += '  text:  \'$dt.text\'\n'
@@ -236,11 +265,13 @@ pub fn (dt DateTime) str() string {
 	return str
 }
 
+// EOF is the data representation of the end of the TOML document.
 pub struct EOF {
 pub:
 	pos token.Position
 }
 
+// str returns the `string` representation of the `EOF` type.
 pub fn (e EOF) str() string {
 	mut str := typeof(e).name + '{\n'
 	str += '  pos:  $e.pos\n'

vlib/toml/checker/checker.v

@@ -14,6 +14,8 @@ pub struct Checker {
 	scanner &scanner.Scanner
 }
 
+// check checks the `ast.Value` and all it's children
+// for common errors.
 pub fn (c Checker) check(n &ast.Value) ? {
 	walker.walk(c, n) ?
 }

vlib/toml/input/input.v

@@ -11,6 +11,8 @@ pub:
 	file_path string // '/path/to/file.toml'
 }
 
+// validate returns an optional error if more than one of the fields
+// in `Config` has a non-default value (empty string).
 pub fn (c Config) validate() ? {
 	if c.file_path != '' && c.text != '' {
 		error(@MOD + '.' + @FN +

vlib/toml/parser/parser.v

@@ -9,9 +9,7 @@ import toml.util
 import toml.token
 import toml.scanner
 
-// Scanner contains the necessary fields for the state of the scan process.
-// the task the scanner does is also refered to as "lexing" or "tokenizing".
-// The Scanner methods are based on much of the work in `vlib/strings/textscanner`.
+// Parser contains the necessary fields for keeping the state of the parsing process.
 pub struct Parser {
 pub:
 	config Config
@@ -31,8 +29,8 @@ mut:
 	ast_root &ast.Root = &ast.Root{}
 }
 
-// Config is used to configure a Scanner instance.
-// Only one of the fields `text` and `file_path` is allowed to be set at time of configuration.
+// Config is used to configure a Parser instance.
+// `run_checks` is used to en- or disable running of the strict `checker.Checker` type checks.
 pub struct Config {
 pub:
 	scanner    &scanner.Scanner
@@ -116,10 +114,11 @@ fn (mut p Parser) expect(expected_token token.Kind) ? {
 	}
 }
 
-// find_table returns a reference to a map if found in the root table given a "dotted" key ('a.b.c').
+// find_table returns a reference to a map if found in the *root* table given a "dotted" key (`a.b.c`).
 // If some segments of the key does not exist in the root table find_table will
 // allocate a new map for each segment. This behavior is needed because you can
 // reference maps by multiple keys "dotted" (separated by "." periods) in TOML documents.
+// See also `find_in_table`.
 pub fn (mut p Parser) find_table() ?&map[string]ast.Value {
 	util.printdbg(@MOD + '.' + @STRUCT + '.' + @FN, 'locating "$p.root_map_key" in map ${ptr_str(p.root_map)}')
 	mut t := &map[string]ast.Value{}
@@ -133,6 +132,8 @@ pub fn (mut p Parser) find_table() ?&map[string]ast.Value {
 	return p.find_in_table(mut t, p.root_map_key)
 }
 
+// sub_table_key returns the logic parts of a dotted key (`a.b.c`) for
+// use with the `find_sub_table` method.
 pub fn (mut p Parser) sub_table_key(key string) (string, string) {
 	mut ks := key.split('.')
 	last := ks.last()
@@ -140,10 +141,11 @@ pub fn (mut p Parser) sub_table_key(key string) (string, string) {
 	return ks.join('.'), last
 }
 
-// find_sub_table returns a reference to a map if found in `table` given a "dotted" key ('aa.bb.cc').
-// If some segments of the key does not exist in the input map find_in_table will
+// find_sub_table returns a reference to a map if found in the *root* table given a "dotted" key (`a.b.c`).
+// If some segments of the key does not exist in the input map find_sub_table will
 // allocate a new map for the segment. This behavior is needed because you can
 // reference maps by multiple keys "dotted" (separated by "." periods) in TOML documents.
+// See also `find_in_table`.
 pub fn (mut p Parser) find_sub_table(key string) ?&map[string]ast.Value {
 	mut ky := p.root_map_key + '.' + key
 	if p.root_map_key == '' {
@@ -161,7 +163,7 @@ pub fn (mut p Parser) find_sub_table(key string) ?&map[string]ast.Value {
 	return p.find_in_table(mut t, ky)
 }
 
-// find_in_table returns a reference to a map if found in `table` given a "dotted" key ('aa.bb.cc').
+// find_in_table returns a reference to a map if found in `table` given a "dotted" key (`a.b.c`).
 // If some segments of the key does not exist in the input map find_in_table will
 // allocate a new map for the segment. This behavior is needed because you can
 // reference maps by multiple keys "dotted" (separated by "." periods) in TOML documents.
@@ -206,6 +208,8 @@ pub fn (mut p Parser) find_in_table(mut table map[string]ast.Value, key string)
 	return t
 }
 
+// sub_key parses next tokens as sub/nested keys. This is the also referred to as
+// a "dotted" key (`a.b.c`). sub_key returns a string in dotted form.
 pub fn (mut p Parser) sub_key() ?string {
 	util.printdbg(@MOD + '.' + @STRUCT + '.' + @FN, 'parsing nested key...')
 	key := p.key() ?

vlib/toml/toml.v

@@ -67,9 +67,9 @@ pub fn parse_text(text string) ?Doc {
 	}
 }
 
-// parse parses the TOML document provided in `input`.
-// parse automatically try to determine if the type of `input` is a file or text.
-// For explicit parsing of input see `parse_file` or `parse_text`.
+// parse parses the TOML document provided in `toml`.
+// parse automatically try to determine if the type of `toml` is a file or text.
+// For explicit parsing of input types see `parse_file` or `parse_text`.
 pub fn parse(toml string) ?Doc {
 	mut input_config := input.Config{}
 	if !toml.contains('\n') && os.is_file(toml) {
@@ -95,7 +95,7 @@ pub fn parse(toml string) ?Doc {
 	}
 }
 
-// to_json returns a compact json string of the complete document
+// to_json returns a compact json string of the complete document.
 pub fn (d Doc) to_json() string {
 	return d.ast.to_json()
 }
@@ -119,7 +119,7 @@ fn (d Doc) ast_to_any(value ast.Value) Any {
 				return Any(Null{})
 				// TODO decide this
 				// panic(@MOD + '.' + @STRUCT + '.' + @FN +
-				//	' failed converting "$date_str" to iso8601: $err')
+				//	' failed converting "$date_str" to rfc3339: $err')
 			}
 		} else if value is ast.Time {
 			time_str := (value as ast.Time).text