docs: use cmd/tools/find_doc_comments_with_no_dots.v to put some missing dots in the doc comments of public symbols.

vlib/cli/command.v

@@ -9,8 +9,7 @@ pub fn (f FnCommandCallback) str() string {
 	return 'FnCommandCallback=>' + ptr_str(f)
 }
 
-// Command is a structured representation of a single command
+// Command is a structured representation of a single command or chain of commands.
-// or chain of commands.
 pub struct Command {
 pub mut:
 	name            string
@@ -147,8 +146,7 @@ pub fn (mut cmd Command) add_command(command Command) {
 	cmd.commands << subcmd
 }
 
-// setup ensures that all sub-commands of this `Command`
+// setup ensures that all sub-commands of this `Command` is linked as a chain.
-// is linked as a chain.
 pub fn (mut cmd Command) setup() {
 	for mut subcmd in cmd.commands {
 		subcmd.parent = unsafe { cmd }
@@ -361,8 +359,7 @@ fn (cmd &Command) check_required_flags() {
 	}
 }
 
-// execute_help executes the callback registered
+// execute_help executes the callback registered for the `-h`/`--help` flag option.
-// for the `-h`/`--help` flag option.
 pub fn (cmd &Command) execute_help() {
 	if cmd.commands.contains('help') {
 		help_cmd := cmd.commands.get('help') or { return } // ignore error and handle command normally
@@ -374,8 +371,7 @@ pub fn (cmd &Command) execute_help() {
 	print(cmd.help_message())
 }
 
-// execute_man executes the callback registered
+// execute_man executes the callback registered for the `-man` flag option.
-// for the `-man` flag option.
 pub fn (cmd &Command) execute_man() {
 	if cmd.commands.contains('man') {
 		man_cmd := cmd.commands.get('man') or { return }

vlib/cli/flag.v

@@ -36,7 +36,7 @@ mut:
 	value []string = []
 }
 
-// get_all_found returns an array of all `Flag`s found in the command parameters
+// get_all_found returns an array of all `Flag`s found in the command parameters.
 pub fn (flags []Flag) get_all_found() []Flag {
 	return flags.filter(it.found)
 }
@@ -210,8 +210,7 @@ pub fn (flags []Flag) get_strings(name string) ![]string {
 	return flag.get_strings()
 }
 
-// parse parses flag values from arguments and return
+// parse parses flag values from arguments and return an array of arguments with all consumed elements removed.
-// an array of arguments with all consumed elements removed.
 pub fn (mut flag Flag) parse(args []string, posix_mode bool) ![]string {
 	return match true {
 		!flag.matches(args[0], posix_mode) {

vlib/cli/man.v

@@ -19,8 +19,7 @@ fn man_cmd() Command {
 	}
 }
 
-// print_manpage_for_command prints the manpage for the
+// print_manpage_for_command prints the manpage for the command or subcommand in `man_cmd` to stdout.
-// command or subcommand in `man_cmd` to stdout
 pub fn print_manpage_for_command(cmd Command) ! {
 	if cmd.args.len > 0 {
 		for sub_cmd in cmd.commands {
@@ -36,8 +35,7 @@ pub fn print_manpage_for_command(cmd Command) ! {
 	}
 }
 
-// manpage returns a `string` containing the mdoc(7) manpage for
+// manpage returns a `string` containing the mdoc(7) manpage for this `Command`.
-// this `Command`
 pub fn (cmd &Command) manpage() string {
 	mut mdoc := '.Dd ${time.now().strftime('%B %d, %Y')}\n'
 	mdoc += '.Dt ${cmd.full_name().replace(' ', '-').to_upper()} 1\n'

vlib/dl/dl_nix.c.v

@@ -36,10 +36,10 @@ pub fn sym(handle voidptr, symbol string) voidptr {
 	return C.dlsym(handle, &char(symbol.str))
 }
 
-// dlerror provides a text error diagnostic message for functions in `dl`
+// dlerror provides a text error diagnostic message for functions in `dl`.
-// it returns a human-readable string, describing the most recent error
+// It returns a human-readable string, describing the most recent error
 // that occurred from a call to one of the `dl` functions, since the last
-// call to dlerror()
+// call to dlerror().
 pub fn dlerror() string {
 	sptr := C.dlerror()
 	if sptr == unsafe { nil } {

vlib/dl/dl_windows.c.v

@@ -33,10 +33,10 @@ pub fn sym(handle voidptr, symbol string) voidptr {
 	return C.GetProcAddress(handle, voidptr(symbol.str))
 }
 
-// dlerror provides a text error diagnostic message for functions in `dl`
+// dlerror provides a text error diagnostic message for functions in `dl`.
-// it returns a human-readable string, describing the most recent error
+// It returns a human-readable string, describing the most recent error
 // that occurred from a call to one of the `dl` functions, since the last
-// call to dlerror()
+// call to dlerror().
 pub fn dlerror() string {
 	// https://docs.microsoft.com/en-us/windows/win32/api/errhandlingapi/nf-errhandlingapi-getlasterror
 	// Unlike dlerror(), GetLastError returns just an error code, that is function specific.

vlib/flag/flag.v

@@ -49,7 +49,7 @@ fn (mut f Flag) free() {
 	}
 }
 
-// str returns a string representation of the given Flag
+// str returns a string representation of the given Flag.
 pub fn (f Flag) str() string {
 	return '    flag:
             name: ${f.name}
@@ -58,7 +58,7 @@ pub fn (f Flag) str() string {
             desc: ${f.val_desc}'
 }
 
-// str returns a string representation of the given array of Flags
+// str returns a string representation of the given array of Flags.
 pub fn (af []Flag) str() string {
 	mut res := []string{}
 	res << '\n  []Flag = ['
@@ -129,7 +129,7 @@ pub const space = '                            '
 pub const underline = '-----------------------------------------------'
 pub const max_args_number = 4048
 
-// new_flag_parser - create a new flag parser for the given args
+// new_flag_parser - create a new flag parser for the given args.
 pub fn new_flag_parser(args []string) &FlagParser {
 	original_args := args.clone()
 	idx_dashdash := args.index('--')
@@ -150,7 +150,7 @@ pub fn new_flag_parser(args []string) &FlagParser {
 	}
 }
 
-// usage_example - add an usage example
+// usage_example - add an usage example.
 // All examples will be listed in the help screen.
 // If you do not give any examples, then a default usage
 // will be shown, based on whether the application takes
@@ -175,8 +175,7 @@ pub fn (mut fs FlagParser) version(vers string) {
 	fs.application_version = vers
 }
 
-// description appends to the application description lines, shown
+// description appends to the application description lines, shown in the help/usage screen.
-// in the help/usage screen
 pub fn (mut fs FlagParser) description(desc string) {
 	if fs.application_description.len == 0 {
 		fs.application_description = desc
@@ -190,15 +189,14 @@ pub fn (mut fs FlagParser) skip_executable() {
 	fs.args.delete(0)
 }
 
-// allow_unknown_args - if your program has sub commands, that have
+// allow_unknown_args - call this method, if your program has sub commands, that have their own arguments.
-// their own arguments, you can call .allow_unknown_args(), so that
+// After calling it, the subcommand arguments (which generally are not known to your parent program),
-// the subcommand arguments (which generally are not known to your
+// will not cause the validation in .finalize() to fail.
-// parent program), will not cause the validation in .finalize() to fail.
 pub fn (mut fs FlagParser) allow_unknown_args() {
 	fs.allow_unknown_args = true
 }
 
-// private helper to register a flag
+// private helper to register a flag.
 // This version supports abbreviations.
 fn (mut fs FlagParser) add_flag(name string, abbr u8, usage string, desc string) {
 	fs.flags << Flag{
@@ -500,9 +498,8 @@ pub fn (mut fs FlagParser) string(name string, abbr u8, sdefault string, usage s
 	return value
 }
 
-// limit_free_args_to_at_least restricts the list of free arguments (non options) to be
+// limit_free_args_to_at_least restricts the list of free arguments (non options) to be at least `n` in length.
-// at least `n` in length. If the user gives less free arguments to the program,
+// If the user gives less free arguments to the program, the parser will return an error.
-// the parser will return an error.
 pub fn (mut fs FlagParser) limit_free_args_to_at_least(n int) ! {
 	if n > max_args_number {
 		return error('flag.limit_free_args_to_at_least expect n to be smaller than ${max_args_number}')
@@ -513,9 +510,8 @@ pub fn (mut fs FlagParser) limit_free_args_to_at_least(n int) ! {
 	fs.min_free_args = n
 }
 
-// limit_free_args_to_exactly restricts the list of free arguments (non options) to be
+// limit_free_args_to_exactly restricts the list of free arguments (non options) to be at exactly `n` in length.
-// at exactly `n` in length. If the user gives more or less free arguments to the program,
+// If the user gives more or less free arguments to the program, the parser will return an error.
-// the parser will return an error.
 pub fn (mut fs FlagParser) limit_free_args_to_exactly(n int) ! {
 	if n > max_args_number {
 		return error('flag.limit_free_args_to_exactly expect n to be smaller than ${max_args_number}')
@@ -527,9 +523,8 @@ pub fn (mut fs FlagParser) limit_free_args_to_exactly(n int) ! {
 	fs.max_free_args = n
 }
 
-// limit_free_args restricts the list of free arguments (non options) to be between
+// limit_free_args restricts the list of free arguments (non options) to be between `min` and `max` in length.
-// `min` and `max` in length. If the user gives more or less free arguments to the program,
+// If the user gives more or less free arguments to the program, the parser will return an error.
-// the parser will return an error.
 pub fn (mut fs FlagParser) limit_free_args(min int, max int) ! {
 	if min > max {
 		return error('flag.limit_free_args expect min < max, got ${min} >= ${max}')
@@ -544,8 +539,7 @@ pub fn (mut fs FlagParser) arguments_description(description string) {
 	fs.args_description = description
 }
 
-// usage returns a nicely formatted usage screen, containing all the
+// usage returns a nicely formatted usage screen, containing all the possible options, as well as the description for the program.
-// possible options, as well as the description for the program.
 // That screen is usually shown when the `--help` option is given to the program.
 pub fn (fs &FlagParser) usage() string {
 	positive_min_arg := (fs.min_free_args > 0)

vlib/flag/flag_to.v

@@ -332,8 +332,7 @@ pub fn using[T](defaults T, input []string, config ParseConfig) !(T, []string) {
 	return st, fm.no_matches()
 }
 
-// to_doc returns a "usage" style documentation `string` generated from
+// to_doc returns a "usage" style documentation `string` generated from attributes on `T` or via the `dc` argument.
-// attributes on `T` or via the `dc` argument.
 pub fn to_doc[T](dc DocConfig) !string {
 	mut fm := FlagMapper{
 		config: ParseConfig{
@@ -346,9 +345,8 @@ pub fn to_doc[T](dc DocConfig) !string {
 	return fm.to_doc(dc)!
 }
 
-// no_matches returns any flags from the `input` array, in order of appearance,
+// no_matches returns any flags from the `input` array, in order of appearance, that could *not* be matched against any fields.
-// that could *not* be matched against any fields.
+// This method should be called *after* `to_struct[T]()`.
-// no_matches should be called *after* `to_struct[T]()`.
 pub fn (fm FlagMapper) no_matches() []string {
 	mut non_matching := []string{}
 	for i in fm.no_match {
@@ -619,8 +617,7 @@ pub fn (mut fm FlagMapper) parse[T]() ! {
 	}
 }
 
-// to_doc returns a "usage" style documentation `string` generated from
+// to_doc returns a "usage" style documentation `string` generated from the internal data structures generated via the `parse()` function.
-// the internal data structures generated via the `parse()` function.
 pub fn (fm FlagMapper) to_doc(dc DocConfig) !string {
 	mut docs := []string{}
 

vlib/hash/crc32/crc32.v

@@ -44,8 +44,7 @@ fn (c &Crc32) sum32(b []u8) u32 {
 	return ~crc
 }
 
-// checksum returns the CRC-32 checksum of data `b` by using the polynomial represented by
+// checksum returns the CRC-32 checksum of data `b` by using the polynomial represented by `c`'s table.
-// `c`'s table.
 pub fn (c &Crc32) checksum(b []u8) u32 {
 	return c.sum32(b)
 }

vlib/picoev/loop_linux.c.v

@@ -36,8 +36,7 @@ mut:
 
 type LoopType = EpollLoop
 
-// create_epoll_loop creates a new epoll instance and returns an
+// create_epoll_loop creates a new epoll instance and returns an `EpollLoop` struct with `id`.
-// `EpollLoop` struct with `id`.
 pub fn create_epoll_loop(id int) !&EpollLoop {
 	mut loop := &EpollLoop{
 		id: id

vlib/picoev/loop_termux.c.v

@@ -36,8 +36,7 @@ mut:
 
 type LoopType = EpollLoop
 
-// create_epoll_loop creates a new epoll instance and returns an
+// create_epoll_loop creates a new epoll instance and returns an `EpollLoop` struct with `id`.
-// `EpollLoop` struct with `id`.
 pub fn create_epoll_loop(id int) !&EpollLoop {
 	mut loop := &EpollLoop{
 		id: id

vlib/picoev/picoev.v

@@ -25,8 +25,7 @@ pub const picoev_del = 0x20000000
 // event read/write.
 pub const picoev_readwrite = 3
 
-// Target is a data representation of everything that needs to be associated with a single
+// Target is a data representation of everything that needs to be associated with a single file descriptor (connection).
-// file descriptor (connection).
 pub struct Target {
 pub mut:
 	fd      int // file descriptor

vlib/runtime/runtime.v

@@ -6,8 +6,8 @@ module runtime
 
 import os
 
-// nr_jobs returns the same as `nr_cpus` with the difference that if an
+// nr_jobs returns the same as `nr_cpus`, but influenced by the env variable `VJOBS`.
-// environment variable `VJOBS` is set, and has a value > 0,
+// If the environment variable `VJOBS` is set, and has a value > 0,
 // then `nr_jobs` will return that number instead.
 // This is useful for runtime tweaking of e.g. threaded or concurrent code.
 pub fn nr_jobs() int {

vlib/v/checker/checker.v

@@ -24,7 +24,7 @@ const generic_fn_cutoff_limit_per_fn = 10_000 // how many times post_process_gen
 
 const generic_fn_postprocess_iterations_cutoff_limit = 1_000_000
 
-// array_builtin_methods contains a list of all methods on array, that return other typed arrays,
+// array_builtin_methods contains a list of all methods on array, that return other typed arrays.
 // i.e. that act as *pseudogeneric* methods, that need compiler support, so that the types of the results
 // are properly checked.
 // Note that methods that do not return anything, or that return known types, are not listed here, since they are just ordinary non generic methods.
@@ -5717,7 +5717,7 @@ fn (c &Checker) check_import_sym_conflict(ident string) bool {
 	return false
 }
 
-// update_unresolved_fixed_sizes updates the unresolved type symbols for array fixed return type and alias type
+// update_unresolved_fixed_sizes updates the unresolved type symbols for array fixed return type and alias type.
 pub fn (mut c Checker) update_unresolved_fixed_sizes() {
 	for mut stmt in c.unresolved_fixed_sizes {
 		if mut stmt is ast.FnDecl { // return types

vlib/v/gen/c/cmain.v

@@ -395,7 +395,7 @@ pub fn (mut g Gen) gen_c_main_trace_calls_hook() {
 	g.writeln('\tu8 bottom_of_stack = 0; g_stack_base = &bottom_of_stack; v__trace_calls__on_c_main(${should_trace_c_main});')
 }
 
-// gen_dll_main create DllMain() for windows .dll
+// gen_dll_main create DllMain() for windows .dll.
 pub fn (mut g Gen) gen_dll_main() {
 	g.writeln('VV_EXP BOOL DllMain(HINSTANCE hinst,DWORD fdwReason,LPVOID lpvReserved) {
 	switch (fdwReason) {

vlib/v/gen/native/amd64.v

@@ -1459,7 +1459,7 @@ fn (mut c Amd64) gen_print(s string, fd i32) {
 	c.g.println('; print }')
 }
 
-// gen_print_reg writes a string of size n stored in r to fd
+// gen_print_reg writes a string of size n stored in r to fd.
 pub fn (mut c Amd64) gen_print_reg(r Register, n i32, fd i32) {
 	c.g.println('; print_reg: (reg:${r} fd:${fd} len:${n}) {')
 	str_reg := if c.g.pref.os == .windows { Amd64Register.rdx } else { Amd64Register.rsi }

vlib/v/gen/wasm/mem.v

@@ -428,9 +428,9 @@ pub fn (mut g Gen) set_set(v Var) {
 	g.mov(v, from)
 }
 
-// set structures with pointer, memcpy
+// set structures with pointer, memcpy.
-// set pointers with value, get local, store value
+// set pointers with value, get local, store value.
-// set value, set local
+// set value, set local.
 // -- set works with a single value present on the stack beforehand
 // -- not optimal for copying stack memory or shuffling structs
 // -- use mov instead

vlib/v/markused/markused.v

@@ -6,7 +6,7 @@ import v.ast
 import v.util
 import v.pref
 
-// mark_used walks the AST, starting at main() and marks all used fns transitively
+// mark_used walks the AST, starting at main() and marks all used fns transitively.
 pub fn mark_used(mut table ast.Table, mut pref_ pref.Preferences, ast_files []&ast.File) {
 	mut all_fns, all_consts, all_globals, all_fields := all_global_decl(ast_files)
 	util.timing_start('MARKUSED')