vlib: update doc comments (#19231)

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