From 0b046c14a8784f47b7bc8aff9becf71bc3c71c54 Mon Sep 17 00:00:00 2001
From: Larpon <Larpon@users.noreply.github.com>
Date: Tue, 5 Apr 2022 12:06:32 +0200
Subject: [PATCH] clipboard: add doc strings to all implementations (#13932)

---
 vlib/clipboard/clipboard_android.c.v   |  3 +++
 vlib/clipboard/clipboard_darwin.c.v    | 14 ++++++++++++++
 vlib/clipboard/clipboard_default.c.v   |  3 +++
 vlib/clipboard/clipboard_solaris.c.v   |  3 +++
 vlib/clipboard/clipboard_windows.c.v   | 14 ++++++++++++++
 vlib/clipboard/dummy/dummy_clipboard.v | 14 ++++++++++++++
 6 files changed, 51 insertions(+)

diff --git a/vlib/clipboard/clipboard_android.c.v b/vlib/clipboard/clipboard_android.c.v
index eb1e6b85cd..cbf8882b52 100644
--- a/vlib/clipboard/clipboard_android.c.v
+++ b/vlib/clipboard/clipboard_android.c.v
@@ -2,6 +2,9 @@ module clipboard
 
 import clipboard.dummy
 
+// Clipboard represents a system clipboard.
+//
+// System "copy" and "paste" actions utilize the clipboard for temporary storage.
 pub type Clipboard = dummy.Clipboard
 
 fn new_clipboard() &Clipboard {
diff --git a/vlib/clipboard/clipboard_darwin.c.v b/vlib/clipboard/clipboard_darwin.c.v
index 13c9ee83cf..b8f04214ee 100644
--- a/vlib/clipboard/clipboard_darwin.c.v
+++ b/vlib/clipboard/clipboard_darwin.c.v
@@ -5,6 +5,9 @@ module clipboard
 #flag -framework Cocoa
 #include "@VEXEROOT/vlib/clipboard/clipboard_darwin.m"
 
+// Clipboard represents a system clipboard.
+//
+// System "copy" and "paste" actions utilize the clipboard for temporary storage.
 pub struct Clipboard {
 	pb             voidptr
 	last_cb_serial i64
@@ -25,21 +28,27 @@ fn new_clipboard() &Clipboard {
 	return cb
 }
 
+// check_availability returns true if the clipboard is ready to be used.
 pub fn (cb &Clipboard) check_availability() bool {
 	return cb.pb != C.NULL
 }
 
+// clear empties the clipboard contents.
 pub fn (mut cb Clipboard) clear() {
 	cb.foo = 0
 	cb.set_text('')
 	//#[cb->pb clearContents];
 }
 
+// free releases all memory associated with the clipboard
+// instance.
 pub fn (mut cb Clipboard) free() {
 	cb.foo = 0
 	// nothing to free
 }
 
+// has_ownership returns true if the contents of
+// the clipboard were created by this clipboard instance.
 pub fn (cb &Clipboard) has_ownership() bool {
 	if cb.last_cb_serial == 0 {
 		return false
@@ -50,10 +59,15 @@ pub fn (cb &Clipboard) has_ownership() bool {
 
 fn C.OSAtomicCompareAndSwapLong()
 
+// set_text transfers `text` to the system clipboard.
+// This is often associated with a *copy* action (`Cmd` + `C`).
 pub fn (mut cb Clipboard) set_text(text string) bool {
 	return C.darwin_set_pasteboard_text(cb.pb, text)
 }
 
+// get_text retrieves the contents of the system clipboard
+// as a `string`.
+// This is often associated with a *paste* action (`Cmd` + `V`).
 pub fn (mut cb Clipboard) get_text() string {
 	cb.foo = 0
 	if isnil(cb.pb) {
diff --git a/vlib/clipboard/clipboard_default.c.v b/vlib/clipboard/clipboard_default.c.v
index d8f65cedff..74628813de 100644
--- a/vlib/clipboard/clipboard_default.c.v
+++ b/vlib/clipboard/clipboard_default.c.v
@@ -2,6 +2,9 @@ module clipboard
 
 import clipboard.x11
 
+// Clipboard represents a system clipboard.
+//
+// System "copy" and "paste" actions utilize the clipboard for temporary storage.
 pub type Clipboard = x11.Clipboard
 
 fn new_clipboard() &Clipboard {
diff --git a/vlib/clipboard/clipboard_solaris.c.v b/vlib/clipboard/clipboard_solaris.c.v
index eb1e6b85cd..cbf8882b52 100644
--- a/vlib/clipboard/clipboard_solaris.c.v
+++ b/vlib/clipboard/clipboard_solaris.c.v
@@ -2,6 +2,9 @@ module clipboard
 
 import clipboard.dummy
 
+// Clipboard represents a system clipboard.
+//
+// System "copy" and "paste" actions utilize the clipboard for temporary storage.
 pub type Clipboard = dummy.Clipboard
 
 fn new_clipboard() &Clipboard {
diff --git a/vlib/clipboard/clipboard_windows.c.v b/vlib/clipboard/clipboard_windows.c.v
index 9ae42d1fce..8585feb44b 100644
--- a/vlib/clipboard/clipboard_windows.c.v
+++ b/vlib/clipboard/clipboard_windows.c.v
@@ -51,6 +51,9 @@ fn C.OpenClipboard(hwnd C.HWND) int
 
 fn C.DestroyWindow(hwnd C.HWND)
 
+// Clipboard represents a system clipboard.
+//
+// System "copy" and "paste" actions utilize the clipboard for temporary storage.
 struct Clipboard {
 	max_retries int
 	retry_delay int
@@ -104,14 +107,18 @@ fn new_clipboard() &Clipboard {
 	return cb
 }
 
+// check_availability returns true if the clipboard is ready to be used.
 pub fn (cb &Clipboard) check_availability() bool {
 	return cb.hwnd != C.HWND(C.NULL)
 }
 
+// has_ownership returns true if the contents of
+// the clipboard were created by this clipboard instance.
 pub fn (cb &Clipboard) has_ownership() bool {
 	return C.GetClipboardOwner() == cb.hwnd
 }
 
+// clear empties the clipboard contents.
 pub fn (mut cb Clipboard) clear() {
 	if !cb.get_clipboard_lock() {
 		return
@@ -121,6 +128,8 @@ pub fn (mut cb Clipboard) clear() {
 	cb.foo = 0
 }
 
+// free releases all memory associated with the clipboard
+// instance.
 pub fn (mut cb Clipboard) free() {
 	C.DestroyWindow(cb.hwnd)
 	cb.foo = 0
@@ -143,6 +152,8 @@ fn to_wide(text string) C.HGLOBAL {
 	return buf
 }
 
+// set_text transfers `text` to the system clipboard.
+// This is often associated with a *copy* action (`Ctrl` + `C`).
 pub fn (mut cb Clipboard) set_text(text string) bool {
 	cb.foo = 0
 	buf := to_wide(text)
@@ -164,6 +175,9 @@ pub fn (mut cb Clipboard) set_text(text string) bool {
 	return true
 }
 
+// get_text retrieves the contents of the system clipboard
+// as a `string`.
+// This is often associated with a *paste* action (`Ctrl` + `V`).
 pub fn (mut cb Clipboard) get_text() string {
 	cb.foo = 0
 	if !cb.get_clipboard_lock() {
diff --git a/vlib/clipboard/dummy/dummy_clipboard.v b/vlib/clipboard/dummy/dummy_clipboard.v
index a3f4f35362..8bfedefe53 100644
--- a/vlib/clipboard/dummy/dummy_clipboard.v
+++ b/vlib/clipboard/dummy/dummy_clipboard.v
@@ -1,5 +1,8 @@
 module dummy
 
+// Clipboard represents a system clipboard.
+//
+// System "copy" and "paste" actions utilize the clipboard for temporary storage.
 pub struct Clipboard {
 mut:
 	text     string // text data sent or received
@@ -19,6 +22,8 @@ pub fn new_primary() &Clipboard {
 	return &Clipboard{}
 }
 
+// set_text transfers `text` to the system clipboard.
+// This is often associated with a *copy* action (`Ctrl` + `C`).
 pub fn (mut cb Clipboard) set_text(text string) bool {
 	cb.text = text
 	cb.is_owner = true
@@ -26,22 +31,31 @@ pub fn (mut cb Clipboard) set_text(text string) bool {
 	return true
 }
 
+// get_text retrieves the contents of the system clipboard
+// as a `string`.
+// This is often associated with a *paste* action (`Ctrl` + `V`).
 pub fn (mut cb Clipboard) get_text() string {
 	return cb.text
 }
 
+// clear empties the clipboard contents.
 pub fn (mut cb Clipboard) clear() {
 	cb.text = ''
 	cb.is_owner = false
 }
 
+// free releases all memory associated with the clipboard
+// instance.
 pub fn (mut cb Clipboard) free() {
 }
 
+// has_ownership returns true if the contents of
+// the clipboard were created by this clipboard instance.
 pub fn (cb &Clipboard) has_ownership() bool {
 	return cb.is_owner
 }
 
+// check_availability returns true if the clipboard is ready to be used.
 pub fn (cb &Clipboard) check_availability() bool {
 	// This is a dummy clipboard implementation,
 	// which can be always used, although it does not do much...