diff --git a/vlib/toml/README.md b/vlib/toml/README.md
index dc2e166418..e88160559f 100644
--- a/vlib/toml/README.md
+++ b/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
diff --git a/vlib/toml/any.v b/vlib/toml/any.v
index b3ab466c98..bc8f7acf08 100644
--- a/vlib/toml/any.v
+++ b/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 {
diff --git a/vlib/toml/ast/ast.v b/vlib/toml/ast/ast.v
index 30920ba561..72bd88d5e0 100644
--- a/vlib/toml/ast/ast.v
+++ b/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'
diff --git a/vlib/toml/ast/types.v b/vlib/toml/ast/types.v
index d6c21e0b4d..30d8174b6d 100644
--- a/vlib/toml/ast/types.v
+++ b/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
 }
diff --git a/vlib/toml/ast/walker/walker.v b/vlib/toml/ast/walker/walker.v
index c418a2002a..c259659da3 100644
--- a/vlib/toml/ast/walker/walker.v
+++ b/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 }
 }
diff --git a/vlib/toml/parser/parser.v b/vlib/toml/parser/parser.v
index f9a6aea4c1..72e7708991 100644
--- a/vlib/toml/parser/parser.v
+++ b/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('.')
 }
diff --git a/vlib/toml/token/token.v b/vlib/toml/token/token.v
index 506d277f6c..08f8c90543 100644
--- a/vlib/toml/token/token.v
+++ b/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{
diff --git a/vlib/toml/toml.v b/vlib/toml/toml.v
index 0a8432410a..f96e88cfa0 100644
--- a/vlib/toml/toml.v
+++ b/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)
diff --git a/vlib/toml/util/util.v b/vlib/toml/util/util.v
index 41b994d9c5..ab5058ff07 100644
--- a/vlib/toml/util/util.v
+++ b/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)