From 90dbf683d5862cf1349a5fdd735ed5a1e3900f2d Mon Sep 17 00:00:00 2001
From: Nahua <kangnahua@gmail.com>
Date: Fri, 20 Jan 2023 10:07:28 +0100
Subject: [PATCH] term: add missing documentation for all remaining public
 functions (#17044)

---
 vlib/term/control.v            | 38 ++++++++++++++++++++++++----------
 vlib/term/ui/input_nix.c.v     |  2 ++
 vlib/term/ui/input_windows.c.v |  2 ++
 vlib/term/ui/ui.v              |  2 ++
 4 files changed, 33 insertions(+), 11 deletions(-)

diff --git a/vlib/term/control.v b/vlib/term/control.v
index 2662ddcc1d..c9cbcbb59c 100644
--- a/vlib/term/control.v
+++ b/vlib/term/control.v
@@ -29,72 +29,88 @@ pub fn move(n int, direction string) {
 	flush_stdout()
 }
 
+// cursor_up moves the cursor up `n` lines.
 pub fn cursor_up(n int) {
 	move(n, 'A')
 }
 
+// cursor_down moves the cursor down `n` lines.
 pub fn cursor_down(n int) {
 	move(n, 'B')
 }
 
+// cursor_forward moves the cursor forward `n` character positions.
 pub fn cursor_forward(n int) {
 	move(n, 'C')
 }
 
+// cursor_back moves the cursor back `n` characters.
 pub fn cursor_back(n int) {
 	move(n, 'D')
 }
 
-// type: 0 -> current cursor position to end of the screen
-// type: 1 -> current cursor position to beginning of the screen
-// type: 2 -> clears entire screen
-// type: 3 -> clears entire screen and also delete scrollback buffer
-
+// erase_display erases display characters based on the given parameter, `t`.
+// `t` can be of the following values in string:
+// `0`: current cursor position to end of the terminal window.
+// `1`: current cursor position to beginning of the terminal
+// window.
+// `2`: clears the entire terminal window.
+// `3`: clears the entire terminal window and also deletes the scrollback buffer.
 pub fn erase_display(t string) {
 	print('\x1b[' + t + 'J')
 	flush_stdout()
 }
 
+// erase_to_end erases from the cursor to the end of the terminal window.
 pub fn erase_toend() {
 	erase_display('0')
 }
 
+// erase_tobeg erases from the cursor to the beginning of the terminal window.
 pub fn erase_tobeg() {
 	erase_display('1')
 }
 
-// clears entire screen and returns cursor to top left-corner
+// erase_clear clears the entire terminal window and returns the cursor to the
+// top left corner.
 pub fn erase_clear() {
 	print('\033[H\033[J')
 	flush_stdout()
 }
 
+// erase_del_clear erases saved lines.
 pub fn erase_del_clear() {
 	erase_display('3')
 }
 
-// type: 0 -> current cursor position to end of the line
-// type: 1 -> current cursor position to beginning of the line
-// type: 2 -> clears entire line
-// Note: Cursor position does not change
+// erase_line erases the current line based on the given parameter, `t`.
+// `t` can be of the following values in string:
+// `0`: current cursor position to the end of the line.
+// `1`: current cursor position to the beginning of the line.
+// `2`: clears the entire line.
+// Note: Cursor position does not change.
 pub fn erase_line(t string) {
 	print('\x1b[' + t + 'K')
 	flush_stdout()
 }
 
+// erase_line_toend erases from the cursor position to the end of the line.
 pub fn erase_line_toend() {
 	erase_line('0')
 }
 
+// erase_line_tobeg erases from the start of the line to the cursor
+// position.
 pub fn erase_line_tobeg() {
 	erase_line('1')
 }
 
+// erase_line_clear erases the entire line.
 pub fn erase_line_clear() {
 	erase_line('2')
 }
 
-// Will make cursor appear if not visible
+// show_cursor makes the cursor appear if it was not visible.
 pub fn show_cursor() {
 	print('\x1b[?25h')
 	flush_stdout()
diff --git a/vlib/term/ui/input_nix.c.v b/vlib/term/ui/input_nix.c.v
index f68c70ad83..f74b450aec 100644
--- a/vlib/term/ui/input_nix.c.v
+++ b/vlib/term/ui/input_nix.c.v
@@ -13,6 +13,7 @@ mut:
 
 const ctx_ptr = &Context(0)
 
+// init initializes the terminal console with Config `cfg`.
 pub fn init(cfg Config) &Context {
 	mut ctx := &Context{
 		cfg: cfg
@@ -42,6 +43,7 @@ fn load_title() {
 	flush_stdout()
 }
 
+// run sets up and starts the terminal.
 pub fn (mut ctx Context) run() ? {
 	if ctx.cfg.use_x11 {
 		ctx.fail('error: x11 backend not implemented yet')
diff --git a/vlib/term/ui/input_windows.c.v b/vlib/term/ui/input_windows.c.v
index da4196ad1e..b2fe2dfc2f 100644
--- a/vlib/term/ui/input_windows.c.v
+++ b/vlib/term/ui/input_windows.c.v
@@ -34,6 +34,7 @@ fn restore_terminal_state() {
 	os.flush()
 }
 
+// init initializes the context of a windows console given the `cfg`.
 pub fn init(cfg Config) &Context {
 	mut ctx := &Context{
 		cfg: cfg
@@ -99,6 +100,7 @@ pub fn init(cfg Config) &Context {
 	return ctx
 }
 
+// run starts the windows console or restarts if it was paused.
 pub fn (mut ctx Context) run() ? {
 	frame_time := 1_000_000 / ctx.cfg.frame_rate
 	mut init_called := false
diff --git a/vlib/term/ui/ui.v b/vlib/term/ui/ui.v
index 691de1b8cf..424838bdf9 100644
--- a/vlib/term/ui/ui.v
+++ b/vlib/term/ui/ui.v
@@ -12,6 +12,7 @@ pub:
 	b u8
 }
 
+// hex returns `c`'s RGB color in hex format.
 pub fn (c Color) hex() string {
 	return '#${c.r.hex()}${c.g.hex()}${c.b.hex()}'
 }
@@ -107,6 +108,7 @@ pub fn (mut ctx Context) reset() {
 	ctx.write('\x1b[0m')
 }
 
+// clear erases the entire terminal window and any saved lines.
 [inline]
 pub fn (mut ctx Context) clear() {
 	ctx.write('\x1b[2J\x1b[3J')