vlib: update doc comments (#19231)

vlib/arrays/arrays.v

@@ -679,8 +679,8 @@ pub fn carray_to_varray[T](c_array_data voidptr, items int) []T {
 	return v_array
 }
 
-// find_first returns the first element that matches the given predicate
-// returns `none`, if there is no match found
+// find_first returns the first element that matches the given predicate.
+// Returns `none` if no match is found.
 // Example: arrays.find_first([1, 2, 3, 4, 5], fn (i int) bool { return i == 3 })? // => 3
 pub fn find_first[T](array []T, predicate fn (elem T) bool) ?T {
 	if array.len == 0 {
@@ -694,8 +694,8 @@ pub fn find_first[T](array []T, predicate fn (elem T) bool) ?T {
 	return none
 }
 
-// find_last returns the last element that matches the given predicate
-// returns `none`, if there is no match found
+// find_last returns the last element that matches the given predicate.
+// Returns `none` if no match is found.
 // Example: arrays.find_last([1, 2, 3, 4, 5], fn (i int) bool { return i == 3})? // => 3
 pub fn find_last[T](array []T, predicate fn (elem T) bool) ?T {
 	if array.len == 0 {

vlib/builtin/map.v

@@ -578,7 +578,7 @@ fn (mut d DenseArray) delete(i int) {
 	}
 }
 
-// Removes the mapping of a particular key from the map.
+// delete removes the mapping of a particular key from the map.
 [unsafe]
 pub fn (mut m map) delete(key voidptr) {
 	mut index, mut meta := m.key_to_index(key)
@@ -618,7 +618,7 @@ pub fn (mut m map) delete(key voidptr) {
 	}
 }
 
-// Returns all keys in the map.
+// keys returns all keys in the map.
 pub fn (m &map) keys() array {
 	mut keys := __new_array(m.len, 0, m.key_bytes)
 	mut item := unsafe { &u8(keys.data) }
@@ -645,7 +645,7 @@ pub fn (m &map) keys() array {
 	return keys
 }
 
-// Returns all values in the map.
+// values returns all values in the map.
 pub fn (m &map) values() array {
 	mut values := __new_array(m.len, 0, m.value_bytes)
 	mut item := unsafe { &u8(values.data) }

vlib/dl/dl.v

@@ -26,8 +26,7 @@ pub fn get_libname(libname string) string {
 	return '${libname}${dl.dl_ext}'
 }
 
-// open_opt - loads the dynamic shared object.
-// Unlike open, open_opt return an option.
+// open_opt tries to load a given dynamic shared object.
 pub fn open_opt(filename string, flags int) !voidptr {
 	shared_object_handle := open(filename, flags)
 	if shared_object_handle == 0 {

vlib/dl/dl_nix.c.v

@@ -23,7 +23,7 @@ fn C.dlclose(handle voidptr) int
 
 fn C.dlerror() &char
 
-// open loads the dynamic shared object.
+// open loads a given dynamic shared object.
 pub fn open(filename string, flags int) voidptr {
 	return C.dlopen(&char(filename.str), flags)
 }

vlib/net/http/cookie.v

@@ -105,7 +105,7 @@ pub fn read_cookies(h map[string][]string, filter string) []&Cookie {
 	return cookies
 }
 
-// Returns the serialization of the cookie for use in a Cookie header
+// str returns the serialization of the cookie for use in a Cookie header
 // (if only Name and Value are set) or a Set-Cookie response
 // header (if other fields are set).
 //

vlib/net/http/request.v

@@ -444,7 +444,7 @@ pub fn parse_multipart_form(body string, boundary string) (map[string]string, ma
 	return form, files
 }
 
-// parse_disposition parses the Content-Disposition header of a multipart form
+// parse_disposition parses the Content-Disposition header of a multipart form.
 // Returns a map of the key="value" pairs
 // Example: assert parse_disposition('Content-Disposition: form-data; name="a"; filename="b"') == {'name': 'a', 'filename': 'b'}
 fn parse_disposition(line string) map[string]string {

vlib/os/environment.c.v

@@ -16,8 +16,8 @@ pub fn getenv(key string) string {
 	return getenv_opt(key) or { '' }
 }
 
-// `getenv_opt` returns the value of the environment variable named by the key
-// If there is not one found, it returns `none`.
+// `getenv_opt` returns the value of a given environment variable.
+// Returns `none` if the environment variable does not exist.
 [manualfree]
 pub fn getenv_opt(key string) ?string {
 	unsafe {

vlib/os/environment.js.v

@@ -21,8 +21,8 @@ pub fn getenv(key string) string {
 	return res
 }
 
-// `getenv_opt` returns the value of the environment variable named by the key.
-// If such an environment variable does not exist, then it returns `none`.
+// `getenv_opt` returns the value of a given environment variable.
+// Returns `none` if the environment variable does not exist.
 pub fn getenv_opt(key string) ?string {
 	#if (!$ENV[key]) return none__;
 

vlib/os/file.c.v

@@ -51,7 +51,7 @@ fn fix_windows_path(path string) string {
 	return p
 }
 
-// open_file can be used to open or create a file with custom flags and permissions and returns a `File` object.
+// open_file tries to open or create a file with custom flags and permissions.
 pub fn open_file(path string, mode string, options ...int) !File {
 	mut flags := 0
 	mut seek_to_end := false
@@ -129,7 +129,7 @@ pub fn open_file(path string, mode string, options ...int) !File {
 	}
 }
 
-// open tries to open a file for reading and returns back a read-only `File` object.
+// open tries to open a file from a given path for reading.
 pub fn open(path string) !File {
 	/*
 	$if linux {

vlib/os/open_uri_default.c.v

@@ -1,5 +1,6 @@
 module os
 
+// open_uri opens a given uri.
 pub fn open_uri(uri string) ! {
 	mut vopen_uri_cmd := getenv('VOPEN_URI_CMD')
 	if vopen_uri_cmd == '' {

vlib/os/open_uri_windows.c.v

@@ -4,6 +4,7 @@ import dl
 
 type ShellExecuteWin = fn (voidptr, &u16, &u16, &u16, &u16, int)
 
+// open_uri opens a given uri.
 pub fn open_uri(uri string) ! {
 	mut vopen_uri_cmd := getenv('VOPEN_URI_CMD')
 	if vopen_uri_cmd != '' {

vlib/os/os.c.v

@@ -1001,7 +1001,8 @@ pub fn chown(path string, owner int, group int) ! {
 	}
 }
 
-// open_append opens `path` file for appending.
+// open_append tries to open a file from a given path.
+// If successfull, it and returns a `File` for appending.
 pub fn open_append(path string) !File {
 	mut file := File{}
 	$if windows {

vlib/os/os.v

@@ -288,7 +288,7 @@ pub fn input_opt(prompt string) ?string {
 }
 
 // input returns a one-line string from stdin, after printing a prompt.
-// In the event of error (end of input), it returns '<EOF>'.
+// Returns '<EOF>' in case of an error (end of input).
 pub fn input(prompt string) string {
 	res := input_opt(prompt) or { return '<EOF>' }
 	return res