From f755118e7cffa3c186807079a92b51a12c696203 Mon Sep 17 00:00:00 2001
From: Turiiya <34311583+ttytm@users.noreply.github.com>
Date: Wed, 30 Aug 2023 07:50:00 +0200
Subject: [PATCH] vlib: update doc comments (#19231)

---
 vlib/arrays/arrays.v         | 8 ++++----
 vlib/builtin/map.v           | 6 +++---
 vlib/dl/dl.v                 | 3 +--
 vlib/dl/dl_nix.c.v           | 2 +-
 vlib/net/http/cookie.v       | 2 +-
 vlib/net/http/request.v      | 2 +-
 vlib/os/environment.c.v      | 4 ++--
 vlib/os/environment.js.v     | 4 ++--
 vlib/os/file.c.v             | 4 ++--
 vlib/os/open_uri_default.c.v | 1 +
 vlib/os/open_uri_windows.c.v | 1 +
 vlib/os/os.c.v               | 3 ++-
 vlib/os/os.v                 | 2 +-
 13 files changed, 22 insertions(+), 20 deletions(-)

diff --git a/vlib/arrays/arrays.v b/vlib/arrays/arrays.v
index becd3b173374b6..9d20ee5771f3df 100644
--- a/vlib/arrays/arrays.v
+++ b/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 {
diff --git a/vlib/builtin/map.v b/vlib/builtin/map.v
index 0bb20b3ec6cfee..aba83235ef5f27 100644
--- a/vlib/builtin/map.v
+++ b/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) }
diff --git a/vlib/dl/dl.v b/vlib/dl/dl.v
index 307a5bb051e667..08646fa1bb6720 100644
--- a/vlib/dl/dl.v
+++ b/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 {
diff --git a/vlib/dl/dl_nix.c.v b/vlib/dl/dl_nix.c.v
index b9d1938d411856..667a166f0a80f8 100644
--- a/vlib/dl/dl_nix.c.v
+++ b/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)
 }
diff --git a/vlib/net/http/cookie.v b/vlib/net/http/cookie.v
index 6d70dcdc062e54..46bb20f6edb9a2 100644
--- a/vlib/net/http/cookie.v
+++ b/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).
 //
diff --git a/vlib/net/http/request.v b/vlib/net/http/request.v
index 42b11084f4ab8e..22e0e8bc719b4d 100644
--- a/vlib/net/http/request.v
+++ b/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 {
diff --git a/vlib/os/environment.c.v b/vlib/os/environment.c.v
index 06fb379c2a9b08..bbcfefc2021fe1 100644
--- a/vlib/os/environment.c.v
+++ b/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 {
diff --git a/vlib/os/environment.js.v b/vlib/os/environment.js.v
index 67ae5bd34508ea..939cfa6a53079e 100644
--- a/vlib/os/environment.js.v
+++ b/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__;
 
diff --git a/vlib/os/file.c.v b/vlib/os/file.c.v
index 0d9b00778a238e..cfc6107deb023a 100644
--- a/vlib/os/file.c.v
+++ b/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 {
diff --git a/vlib/os/open_uri_default.c.v b/vlib/os/open_uri_default.c.v
index 1a517239876599..598f04adabbfd8 100644
--- a/vlib/os/open_uri_default.c.v
+++ b/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 == '' {
diff --git a/vlib/os/open_uri_windows.c.v b/vlib/os/open_uri_windows.c.v
index f786ba5ce15d4a..5f8d48790f1605 100644
--- a/vlib/os/open_uri_windows.c.v
+++ b/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 != '' {
diff --git a/vlib/os/os.c.v b/vlib/os/os.c.v
index 7ebd34a8ed47d7..e6e5c3f8474f2c 100644
--- a/vlib/os/os.c.v
+++ b/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 {
diff --git a/vlib/os/os.v b/vlib/os/os.v
index d70bdf0d09c5f8..22ca92463847c0 100644
--- a/vlib/os/os.v
+++ b/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