strconv: add missing doc strings (#14164)

vlib/strconv/f32_str.c.v

@@ -322,7 +322,7 @@ fn f32_to_decimal(mant u32, exp u32) Dec32 {
 // String Functions
 //=============================================================================
 
-// f32_to_str return a string in scientific notation with max n_digit after the dot
+// f32_to_str returns a `string` in scientific notation with max `n_digit` after the dot.
 pub fn f32_to_str(f f32, n_digit int) string {
 	mut u1 := Uf32{}
 	u1.f = f
@@ -349,7 +349,7 @@ pub fn f32_to_str(f f32, n_digit int) string {
 	return d.get_string_32(neg, n_digit, 0)
 }
 
-// f32_to_str return a string in scientific notation with max n_digit after the dot
+// f32_to_str_pad returns a `string` in scientific notation with max `n_digit` after the dot.
 pub fn f32_to_str_pad(f f32, n_digit int) string {
 	mut u1 := Uf32{}
 	u1.f = f

vlib/strconv/f64_str.c.v

@@ -331,7 +331,7 @@ fn f64_to_decimal(mant u64, exp u64) Dec64 {
 // String Functions
 //=============================================================================
 
-// f64_to_str return a string in scientific notation with max n_digit after the dot
+// f64_to_str returns `f` as a `string` in scientific notation with max `n_digit` digits after the dot.
 pub fn f64_to_str(f f64, n_digit int) string {
 	mut u1 := Uf64{}
 	u1.f = f
@@ -356,7 +356,7 @@ pub fn f64_to_str(f f64, n_digit int) string {
 	return d.get_string_64(neg, n_digit, 0)
 }
 
-// f64_to_str return a string in scientific notation with max n_digit after the dot
+// f64_to_str returns `f` as a `string` in scientific notation with max `n_digit` digits after the dot.
 pub fn f64_to_str_pad(f f64, n_digit int) string {
 	mut u1 := Uf64{}
 	u1.f = f

vlib/strconv/format.v

@@ -89,6 +89,7 @@ pub mut:
 	rm_tail_zero bool       // remove the tail zeros from floats
 }
 
+// format_str returns a `string` formatted according to the options set in `p`.
 [manualfree]
 pub fn format_str(s string, p BF_param) string {
 	if p.len0 <= 0 {

vlib/strconv/format_mem.c.v

@@ -9,7 +9,7 @@ module strconv
 
 import strings
 
-// strings.Builder version of format_str
+// format_str_sb is a `strings.Builder` version of `format_str`.
 pub fn format_str_sb(s string, p BF_param, mut sb strings.Builder) {
 	if p.len0 <= 0 {
 		sb.write_string(s)
@@ -40,7 +40,7 @@ const (
 	digit_pairs       = '00102030405060708090011121314151617181910212223242526272829203132333435363738393041424344454647484940515253545556575859506162636465666768696071727374757677787970818283848586878889809192939495969798999'
 )
 
-// format_dec_sb format a u64
+// format_dec_sb formats an u64 using a `strings.Builder`.
 [direct_array_access]
 pub fn format_dec_sb(d u64, p BF_param, mut res strings.Builder) {
 	mut n_char := dec_digits(d)
@@ -135,8 +135,9 @@ pub fn format_dec_sb(d u64, p BF_param, mut res strings.Builder) {
 	return
 }
 
+// f64_to_str_lnd1 formats a f64 to a `string` with `dec_digit` digits after the dot.
 [direct_array_access; manualfree]
-pub fn f64_to_str_lnd1(f f64, dec_digit int) string {
+fn f64_to_str_lnd1(f f64, dec_digit int) string {
 	unsafe {
 		// we add the rounding value
 		s := f64_to_str(f + dec_round[dec_digit], 18)
@@ -311,7 +312,7 @@ pub fn f64_to_str_lnd1(f f64, dec_digit int) string {
 	}
 }
 
-// strings.Builder version of format_fl
+// format_fl is a `strings.Builder` version of format_fl.
 [direct_array_access; manualfree]
 pub fn format_fl(f f64, p BF_param) string {
 	unsafe {
@@ -388,6 +389,7 @@ pub fn format_fl(f f64, p BF_param) string {
 	}
 }
 
+// format_es returns a f64 as a `string` formatted according to the options set in `p`.
 [direct_array_access; manualfree]
 pub fn format_es(f f64, p BF_param) string {
 	unsafe {
@@ -458,6 +460,7 @@ pub fn format_es(f f64, p BF_param) string {
 	}
 }
 
+// remove_tail_zeros strips traling zeros from `s` and return the resulting `string`.
 [direct_array_access]
 pub fn remove_tail_zeros(s string) string {
 	unsafe {

vlib/strconv/ftoa.c.v

@@ -18,21 +18,33 @@ inspired by the Go version here:
 https://github.com/cespare/ryu/tree/ba56a33f39e3bbbfa409095d0f9ae168a595feea
 */
 
+// ftoa_64 returns a string in scientific notation with max 17 digits after the dot.
+//
+// Example: assert strconv.ftoa_64(123.1234567891011121) == '1.2312345678910111e+02'
 [inline]
 pub fn ftoa_64(f f64) string {
 	return f64_to_str(f, 17)
 }
 
+// ftoa_long_64 returns `f` as a `string` in decimal notation with a maximum of 17 digits after the dot.
+//
+// Example: assert strconv.f64_to_str_l(123.1234567891011121) == '123.12345678910111'
 [inline]
 pub fn ftoa_long_64(f f64) string {
 	return f64_to_str_l(f)
 }
 
+// ftoa_32 returns a `string` in scientific notation with max 8 digits after the dot.
+//
+// Example: assert strconv.ftoa_32(34.1234567) == '3.4123455e+01'
 [inline]
 pub fn ftoa_32(f f32) string {
 	return f32_to_str(f, 8)
 }
 
+// ftoa_long_32 returns `f` as a `string` in decimal notation with a maximum of 6 digits after the dot.
+//
+// Example: assert strconv.ftoa_long_32(34.1234567) == '34.12346'
 [inline]
 pub fn ftoa_long_32(f f32) string {
 	return f32_to_str_l(f)

vlib/strconv/utilities.c.v

@@ -25,7 +25,9 @@ f64 to string with string format
 */
 
 // TODO: Investigate precision issues
-// f32_to_str_l return a string with the f32 converted in a string in decimal notation
+// f32_to_str_l returns `f` as a `string` in decimal notation with a maximum of 6 digits after the dot.
+//
+// Example: assert strconv.f32_to_str_l(34.1234567) == '34.12346'
 [manualfree]
 pub fn f32_to_str_l(f f32) string {
 	s := f32_to_str(f, 6)
@@ -34,6 +36,10 @@ pub fn f32_to_str_l(f f32) string {
 	return res
 }
 
+// f32_to_str_l_no_dot returns `f` as a `string` in decimal notation with a maximum of 6 digits after the dot.
+// The decimal digits after the dot can be omitted.
+//
+// Example: assert strconv.f32_to_str_l_no_dot(34.) == '34'
 [manualfree]
 pub fn f32_to_str_l_no_dot(f f32) string {
 	s := f32_to_str(f, 6)
@@ -42,6 +48,9 @@ pub fn f32_to_str_l_no_dot(f f32) string {
 	return res
 }
 
+// f64_to_str_l returns `f` as a `string` in decimal notation with a maximum of 18 digits after the dot.
+//
+// Example: assert strconv.f64_to_str_l(123.1234567891011121) == '123.12345678910111'
 [manualfree]
 pub fn f64_to_str_l(f f64) string {
 	s := f64_to_str(f, 18)
@@ -50,6 +59,10 @@ pub fn f64_to_str_l(f f64) string {
 	return res
 }
 
+// f64_to_str_l_no_dot returns `f` as a `string` in decimal notation with a maximum of 18 digits after the dot.
+// The decimal digits after the dot can be omitted.
+//
+// Example: assert strconv.f64_to_str_l_no_dot (34.) == '34'
 [manualfree]
 pub fn f64_to_str_l_no_dot(f f64) string {
 	s := f64_to_str(f, 18)
@@ -58,7 +71,10 @@ pub fn f64_to_str_l_no_dot(f f64) string {
 	return res
 }
 
-// f64_to_str_l return a string with the f64 converted in a string in decimal notation
+// fxx_to_str_l_parse returns a `string` in decimal notation converted from a
+// floating-point `string` in scientific notation.
+//
+// Example: assert strconv.fxx_to_str_l_parse('34.22e+00') == '34.22'
 [manualfree]
 pub fn fxx_to_str_l_parse(s string) string {
 	// check for +inf -inf Nan
@@ -181,7 +197,11 @@ pub fn fxx_to_str_l_parse(s string) string {
 	return unsafe { tos(res.data, r_i) }
 }
 
-// f64_to_str_l return a string with the f64 converted in a string in decimal notation
+// fxx_to_str_l_parse_no_dot returns a `string` in decimal notation converted from a
+// floating-point `string` in scientific notation.
+// The decimal digits after the dot can be omitted.
+//
+// Example: assert strconv.fxx_to_str_l_parse_no_dot ('34.e+01') == '340'
 [manualfree]
 pub fn fxx_to_str_l_parse_no_dot(s string) string {
 	// check for +inf -inf Nan

vlib/strconv/vprintf.c.v

@@ -22,10 +22,18 @@ enum Char_parse_state {
 	reset_params
 }
 
+// v_printf prints a sprintf-like formated `string` to the terminal.
 pub fn v_printf(str string, pt ...voidptr) {
 	print(v_sprintf(str, ...pt))
 }
 
+// v_sprintf returns a sprintf-like formated `string`.
+//
+// Example:
+// ```v
+// x := 3.141516
+// assert strconv.v_sprintf('aaa %G', x) == 'aaa 3.141516'
+// ```
 [manualfree]
 pub fn v_sprintf(str string, pt ...voidptr) string {
 	mut res := strings.new_builder(pt.len * 16)
@@ -628,7 +636,7 @@ pub fn format_fl_old(f f64, p BF_param) string {
 }
 
 [manualfree]
-pub fn format_es_old(f f64, p BF_param) string {
+fn format_es_old(f f64, p BF_param) string {
 	unsafe {
 		mut s := ''
 		mut fs := f64_to_str_pad(if f > 0 { f } else { -f }, p.len1)
@@ -692,7 +700,7 @@ pub fn format_es_old(f f64, p BF_param) string {
 	}
 }
 
-pub fn remove_tail_zeros_old(s string) string {
+fn remove_tail_zeros_old(s string) string {
 	mut i := 0
 	mut last_zero_start := -1
 	mut dot_pos := -1