docs: cleanup doc comments of public APIs in builtin (found by find_doc_comments_with_no_dots.v)

Author: spytheman

vlib/builtin/array.v

@@ -186,8 +186,8 @@ fn new_array_from_c_array_no_alloc(len int, cap int, elm_size int, c_array voidp
 	return arr
 }
 
-// ensure_cap increases the `cap` of an array to the required value
-// by copying the data to a new memory location (creating a clone),
+// ensure_cap increases the `cap` of an array to the required value, if needed.
+// It does so by copying the data to a new memory location (creating a clone),
 // unless `a.cap` is already large enough.
 pub fn (mut a array) ensure_cap(required int) {
 	if required <= a.cap {
@@ -916,8 +916,8 @@ pub fn (mut a array) sort_with_compare(callback fn (voidptr, voidptr) int) {
 	}
 }
 
-// sorted_with_compare sorts a clone of the array, using the results of the
-// given function to determine sort order. The original array is not modified.
+// sorted_with_compare sorts a clone of the array. The original array is not modified.
+// It uses the results of the given function to determine sort order.
 // See also .sort_with_compare()
 pub fn (a &array) sorted_with_compare(callback fn (voidptr, voidptr) int) array {
 	$if freestanding {
@@ -930,15 +930,14 @@ pub fn (a &array) sorted_with_compare(callback fn (voidptr, voidptr) int) array
 	return array{}
 }
 
-// contains determines whether an array includes a certain value among its elements
+// contains determines whether an array includes a certain value among its elements.
 // It will return `true` if the array contains an element with this value.
 // It is similar to `.any` but does not take an `it` expression.
 //
 // Example: [1, 2, 3].contains(4) == false
 pub fn (a array) contains(value voidptr) bool
 
-// index returns the first index at which a given element can be found in the array
-// or `-1` if the value is not found.
+// index returns the first index at which a given element can be found in the array or `-1` if the value is not found.
 pub fn (a array) index(value voidptr) int
 
 @[direct_array_access; unsafe]
@@ -955,7 +954,7 @@ pub fn (mut a []string) free() {
 // The following functions are type-specific functions that apply
 // to arrays of different types in different ways.
 
-// str returns a string representation of an array of strings
+// str returns a string representation of an array of strings.
 // Example: ['a', 'b', 'c'].str() // => "['a', 'b', 'c']".
 @[direct_array_access; manualfree]
 pub fn (a []string) str() string {

vlib/builtin/backtraces.c.v

@@ -1,6 +1,6 @@
 module builtin
 
-// print_backtrace shows a backtrace of the current call stack on stdout
+// print_backtrace shows a backtrace of the current call stack on stdout.
 pub fn print_backtrace() {
 	// At the time of backtrace_symbols_fd call, the C stack would look something like this:
 	// * print_backtrace_skipping_top_frames

vlib/builtin/backtraces_nix.c.v

@@ -1,6 +1,6 @@
 module builtin
 
-// print_backtrace_skipping_top_frames prints the backtrace skipping N top frames
+// print_backtrace_skipping_top_frames prints the backtrace skipping N top frames.
 pub fn print_backtrace_skipping_top_frames(xskipframes int) bool {
 	$if no_backtrace ? {
 		return false

vlib/builtin/backtraces_windows.c.v

@@ -3,7 +3,7 @@ module builtin
 // dbghelp.h is already included in cheaders.v
 #flag windows -l dbghelp
 
-// SymbolInfo is used by print_backtrace_skipping_top_frames_msvc
+// SymbolInfo is used by print_backtrace_skipping_top_frames_msvc.
 pub struct SymbolInfo {
 pub mut:
 	f_size_of_struct u32 // must be 88 to be recognised by SymFromAddr
@@ -61,7 +61,7 @@ const symopt_include_32bit_modules = 0x00002000
 const symopt_allow_zero_address = 0x01000000
 const symopt_debug = u32(0x80000000)
 
-// print_backtrace_skipping_top_frames prints the backtrace skipping N top frames
+// print_backtrace_skipping_top_frames prints the backtrace skipping N top frames.
 pub fn print_backtrace_skipping_top_frames(skipframes int) bool {
 	$if msvc {
 		return print_backtrace_skipping_top_frames_msvc(skipframes)

vlib/builtin/builtin.c.v

@@ -757,6 +757,7 @@ pub fn memdup_uncollectable(src voidptr, sz isize) voidptr {
 	}
 }
 
+// GCHeapUsage contains stats about the current heap usage of your program.
 pub struct GCHeapUsage {
 pub:
 	heap_size      usize
@@ -766,7 +767,7 @@ pub:
 	bytes_since_gc usize
 }
 
-// gc_heap_usage returns the info about heap usage
+// gc_heap_usage returns the info about heap usage.
 pub fn gc_heap_usage() GCHeapUsage {
 	$if gcboehm ? {
 		mut res := GCHeapUsage{}
@@ -778,7 +779,7 @@ pub fn gc_heap_usage() GCHeapUsage {
 	}
 }
 
-// gc_memory_use returns the total memory use in bytes by all allocated blocks
+// gc_memory_use returns the total memory use in bytes by all allocated blocks.
 pub fn gc_memory_use() usize {
 	$if gcboehm ? {
 		return C.GC_get_memory_use()

vlib/builtin/builtin.v

@@ -36,8 +36,7 @@ fn __as_cast(obj voidptr, obj_type int, expected_type int) voidptr {
 	return obj
 }
 
-// VAssertMetaInfo is used during assertions. An instance of it is filled in by
-// compile time generated code, when an assertion fails.
+// VAssertMetaInfo is used during assertions. An instance of it is filled in by compile time generated code, when an assertion fails.
 pub struct VAssertMetaInfo {
 pub:
 	fpath   string // the source file path of the assertion

vlib/builtin/builtin_d_gcboehm.c.v

@@ -178,15 +178,14 @@ pub fn gc_enable() {
 	C.GC_enable()
 }
 
-// gc_disable explicitly disables the GC. Do not forget to enable it again by calling gc_enable(),
-// when your program is otherwise idle, and can afford it.
+// gc_disable explicitly disables the GC. Do not forget to enable it again by calling gc_enable(), when your program is otherwise idle, and can afford it.
 // See also gc_enable() and gc_collect().
 // Note that gc_disable() is a NOP with `-gc none`.
 pub fn gc_disable() {
 	C.GC_disable()
 }
 
-// for leak detection it is advisable to do explicit garbage collections
+// gc_check_leaks is useful for leak detection (it does an explicit garbage collections, but only when a program is compiled with `-gc boehm_leak`).
 pub fn gc_check_leaks() {
 	$if gcboehm_leak ? {
 		C.GC_gcollect()
@@ -220,18 +219,19 @@ fn C.GC_remove_roots(voidptr, voidptr)
 fn C.GC_get_sp_corrector() fn (voidptr, voidptr)
 fn C.GC_set_sp_corrector(fn (voidptr, voidptr))
 
-// GC warnings are silenced by default, but can be redirected to a custom cb function by programs too:
+// FnGC_WarnCB is the type of the callback, that you have to define, if you want to redirect GC warnings and handle them.
+// Note: GC warnings are silenced by default. Use gc_set_warn_proc/1 to set your own handler for them.
 pub type FnGC_WarnCB = fn (msg &char, arg usize)
 
 fn C.GC_get_warn_proc() FnGC_WarnCB
 fn C.GC_set_warn_proc(cb FnGC_WarnCB)
 
-// gc_get_warn_proc returns the current callback fn, that will be used for printing GC warnings
+// gc_get_warn_proc returns the current callback fn, that will be used for printing GC warnings.
 pub fn gc_get_warn_proc() FnGC_WarnCB {
 	return C.GC_get_warn_proc()
 }
 
-// gc_set_warn_proc sets the callback fn, that will be used for printing GC warnings
+// gc_set_warn_proc sets the callback fn, that will be used for printing GC warnings.
 pub fn gc_set_warn_proc(cb FnGC_WarnCB) {
 	C.GC_set_warn_proc(cb)
 }

vlib/builtin/builtin_notd_gcboehm.c.v

@@ -39,8 +39,8 @@ pub fn gc_is_enabled() bool {
 // Note that gc_enable() is a NOP with `-gc none`.
 pub fn gc_enable() {}
 
-// gc_disable explicitly disables the GC. Do not forget to enable it again by calling gc_enable(),
-// when your program is otherwise idle, and can afford it.
+// gc_disable explicitly disables the GC.
+// Do not forget to enable it again by calling gc_enable(), when your program is otherwise idle, and can afford it.
 // See also gc_enable() and gc_collect().
 // Note that gc_disable() is a NOP with `-gc none`.
 pub fn gc_disable() {}

vlib/builtin/int.v

@@ -9,23 +9,23 @@ pub struct VContext {
 
 pub type byte = u8
 
-// ptr_str returns the address of `ptr` as a `string`.
+// ptr_str returns a string with the address of `ptr`.
 pub fn ptr_str(ptr voidptr) string {
 	buf1 := u64(ptr).hex()
 	return buf1
 }
 
-// str returns string equivalent of x
+// str returns the string equivalent of x.
 pub fn (x isize) str() string {
 	return i64(x).str()
 }
 
-// str returns string equivalent of x
+// str returns the string equivalent of x.
 pub fn (x usize) str() string {
 	return u64(x).str()
 }
 
-// str returns string equivalent of cptr
+// str returns a string with the address stored in the pointer cptr.
 pub fn (cptr &char) str() string {
 	return u64(cptr).hex()
 }
@@ -63,10 +63,10 @@ pub const max_u32 = u32(4294967295)
 pub const min_u64 = u64(0)
 pub const max_u64 = u64(18446744073709551615)
 
-// This implementation is the quickest with gcc -O2
 // str_l returns the string representation of the integer nn with max chars.
 @[direct_array_access; inline]
 fn (nn int) str_l(max int) string {
+	// This implementation is the quickest with gcc -O2
 	unsafe {
 		mut n := i64(nn)
 		mut d := 0
@@ -554,10 +554,9 @@ pub fn (b []u8) bytestr() string {
 	}
 }
 
-// byterune attempts to decode a sequence of bytes
-// from utf8 to utf32 and return the result as a rune
-// it will produce an error if there are more than
-// four bytes in the array.
+// byterune attempts to decode a sequence of bytes, from utf8 to utf32.
+// It return the result as a rune.
+// It will produce an error, if there are more than four bytes in the array.
 pub fn (b []u8) byterune() !rune {
 	r := b.utf8_to_utf32()!
 	return rune(r)

vlib/builtin/js/array.js.v

@@ -67,8 +67,7 @@ fn v_sort(mut arr array, comparator fn (voidptr, voidptr) int) {
 	}
 }
 
-// trim trims the array length to "index" without modifying the allocated data. If "index" is greater
-// than len nothing will be changed.
+// trim trims the array length to "index" without modifying the allocated data. If "index" is greater than len nothing will be changed.
 pub fn (mut a array) trim(index int) {
 	if index < a.len {
 		a.len = index
@@ -285,7 +284,7 @@ fn arr_copy(mut dst array, src array, count int) {
 	}
 }
 
-// delete_many deletes `size` elements beginning with index `i`
+// delete_many deletes `size` elements beginning with index `i`.
 pub fn (mut a array) delete_many(i int, size int) {
 	#a.val.arr.make_copy()
 	#a.val.arr.arr.splice(i.valueOf(),size.valueOf())
@@ -320,8 +319,7 @@ pub fn (mut a array) clear() {
 	#a.val.arr.arr.length = 0
 }
 
-// reduce executes a given reducer function on each element of the array,
-// resulting in a single output value.
+// reduce executes a given reducer function on each element of the array, resulting in a single output value.
 pub fn (a array) reduce(iter fn (int, int) int, accum_start int) int {
 	mut accum_ := accum_start
 	/*#for (let i = 0;i < a.arr.length;i++)  {