From 62c2168b0b475463d5c2051d992de88f52299d53 Mon Sep 17 00:00:00 2001 From: Larpon Date: Thu, 21 Jan 2021 12:45:59 +0100 Subject: [PATCH] clipboard: document all pub functions, adhere to vdoc style (#8243) --- vlib/clipboard/clipboard.v | 15 +++++---- vlib/clipboard/clipboard_darwin.c.v | 4 ++- vlib/clipboard/clipboard_default.c.v | 2 ++ vlib/clipboard/clipboard_solaris.c.v | 2 ++ vlib/clipboard/clipboard_windows.c.v | 6 ++-- vlib/clipboard/dummy/dummy_clipboard.v | 8 +++-- vlib/clipboard/x11/clipboard.c.v | 44 ++++++++++++++++---------- 7 files changed, 53 insertions(+), 28 deletions(-) diff --git a/vlib/clipboard/clipboard.v b/vlib/clipboard/clipboard.v index 6d4ebffac4..d82289b1d0 100644 --- a/vlib/clipboard/clipboard.v +++ b/vlib/clipboard/clipboard.v @@ -1,36 +1,37 @@ module clipboard -// create a new clipboard +// new returns a new `Clipboard` instance allocated on the heap. +// The `Clipboard` resources can be released with `free()` pub fn new() &Clipboard { return new_clipboard() } -// copy some text into the clipboard +// copy copies `text` into the clipboard. pub fn (mut cb Clipboard) copy(text string) bool { return cb.set_text(text) } -// get the text from the clipboard +// paste returns current entry as a `string` from the clipboard. pub fn (mut cb Clipboard) paste() string { return cb.get_text() } -// clear the clipboard +// clear_all clears the clipboard. pub fn (mut cb Clipboard) clear_all() { cb.clear() } -// destroy the clipboard +// destroy destroys the clipboard and free it's resources. pub fn (mut cb Clipboard) destroy() { cb.free() } -// check if we own the clipboard +// check_ownership returns `true` if the `Clipboard` has the content ownership. pub fn (cb Clipboard) check_ownership() bool { return cb.has_ownership() } -// check if clipboard can be used +// is_available returns `true` if the clipboard is available for use. pub fn (cb &Clipboard) is_available() bool { return cb.check_availability() } diff --git a/vlib/clipboard/clipboard_darwin.c.v b/vlib/clipboard/clipboard_darwin.c.v index 803d8e7d17..dc98a0b587 100644 --- a/vlib/clipboard/clipboard_darwin.c.v +++ b/vlib/clipboard/clipboard_darwin.c.v @@ -8,7 +8,7 @@ pub struct Clipboard { pb voidptr last_cb_serial i64 mut: - foo int // TODO remove, for mut hack + foo int // TODO remove, for mut hack } fn C.darwin_new_pasteboard() voidptr @@ -62,6 +62,8 @@ fn (mut cb Clipboard) get_text() string { return unsafe { utf8_clip.vstring() } } +// new_primary returns a new X11 `PRIMARY` type `Clipboard` instance allocated on the heap. +// Please note: new_primary only works on X11 based systems. pub fn new_primary() &Clipboard { panic('Primary clipboard is not supported on non-Linux systems.') } diff --git a/vlib/clipboard/clipboard_default.c.v b/vlib/clipboard/clipboard_default.c.v index 0572feeddf..d8f65cedff 100644 --- a/vlib/clipboard/clipboard_default.c.v +++ b/vlib/clipboard/clipboard_default.c.v @@ -8,6 +8,8 @@ fn new_clipboard() &Clipboard { return x11.new_clipboard() } +// new_primary returns a new X11 `PRIMARY` type `Clipboard` instance allocated on the heap. +// Please note: new_primary only works on X11 based systems. pub fn new_primary() &Clipboard { return x11.new_primary() } diff --git a/vlib/clipboard/clipboard_solaris.c.v b/vlib/clipboard/clipboard_solaris.c.v index d0e1094155..eb1e6b85cd 100644 --- a/vlib/clipboard/clipboard_solaris.c.v +++ b/vlib/clipboard/clipboard_solaris.c.v @@ -8,6 +8,8 @@ fn new_clipboard() &Clipboard { return dummy.new_clipboard() } +// new_primary returns a new X11 `PRIMARY` type `Clipboard` instance allocated on the heap. +// Please note: new_primary only works on X11 based systems. pub fn new_primary() &Clipboard { return dummy.new_primary() } diff --git a/vlib/clipboard/clipboard_windows.c.v b/vlib/clipboard/clipboard_windows.c.v index 1aba3b1175..b147024ab2 100644 --- a/vlib/clipboard/clipboard_windows.c.v +++ b/vlib/clipboard/clipboard_windows.c.v @@ -54,8 +54,8 @@ struct Clipboard { max_retries int retry_delay int mut: - hwnd C.HWND - foo int // TODO remove + hwnd C.HWND + foo int // TODO remove } fn (cb &Clipboard) get_clipboard_lock() bool { @@ -178,6 +178,8 @@ fn (mut cb Clipboard) get_text() string { return str } +// new_primary returns a new X11 `PRIMARY` type `Clipboard` instance allocated on the heap. +// Please note: new_primary only works on X11 based systems. pub fn new_primary() &Clipboard { panic('Primary clipboard is not supported on non-Linux systems.') } diff --git a/vlib/clipboard/dummy/dummy_clipboard.v b/vlib/clipboard/dummy/dummy_clipboard.v index a42f7dfc95..cd3314396e 100644 --- a/vlib/clipboard/dummy/dummy_clipboard.v +++ b/vlib/clipboard/dummy/dummy_clipboard.v @@ -3,14 +3,18 @@ module dummy pub struct Clipboard { mut: text string // text data sent or received - got_text bool // used to confirm that we have got the text - is_owner bool // to save selection owner state + got_text bool // used to confirm that we have got the text + is_owner bool // to save selection owner state } +// new_clipboard returns a new `Clipboard` instance allocated on the heap. +// The `Clipboard` resources can be released with `free()` pub fn new_clipboard() &Clipboard { return &Clipboard{} } +// new_primary returns a new X11 `PRIMARY` type `Clipboard` instance allocated on the heap. +// Please note: new_primary only works on X11 based systems. pub fn new_primary() &Clipboard { return &Clipboard{} } diff --git a/vlib/clipboard/x11/clipboard.c.v b/vlib/clipboard/x11/clipboard.c.v index 50b2029056..593a918484 100644 --- a/vlib/clipboard/x11/clipboard.c.v +++ b/vlib/clipboard/x11/clipboard.c.v @@ -157,12 +157,14 @@ struct Property { data byteptr } +// new_clipboard returns a new `Clipboard` instance allocated on the heap. +// The `Clipboard` resources can be released with `free()` pub fn new_clipboard() &Clipboard { return new_x11_clipboard(.clipboard) } -// Initialize a new clipboard of the given selection type. -// We can initialize multiple clipboard instances and use them separately +// new_x11_clipboard initializes a new clipboard of the given selection type. +// Multiple clipboard instance types can be initialized and used separately. fn new_x11_clipboard(selection AtomType) &Clipboard { if selection !in [.clipboard, .primary, .secondary] { panic('Wrong AtomType. Must be one of .primary, .secondary or .clipboard.') @@ -225,6 +227,7 @@ fn (cb &Clipboard) take_ownership() { C.XFlush(cb.display) } +// set_text stores `text` in the system clipboard. pub fn (mut cb Clipboard) set_text(text string) bool { if cb.window == C.Window(C.None) { return false @@ -265,8 +268,8 @@ fn (mut cb Clipboard) get_text() string { return cb.text } -// this function is crucial to handling all the different data types -// if we ever support other mimetypes they should be handled here +// transmit_selection is crucial to handling all the different data types. +// If we ever support other mimetypes they should be handled here. fn (mut cb Clipboard) transmit_selection(xse &C.XSelectionEvent) bool { if xse.target == cb.get_atom(.targets) { targets := cb.get_supported_targets() @@ -301,8 +304,9 @@ fn (mut cb Clipboard) start_listener() { } } C.SelectionClear { - if unsafe { event.xselectionclear.window == cb.window } && unsafe { event.xselectionclear.selection == - cb.selection } + if unsafe { event.xselectionclear.window == cb.window } && unsafe { + event.xselectionclear.selection == cb.selection + } { cb.mutex.m_lock() cb.is_owner = false @@ -334,8 +338,9 @@ fn (mut cb Clipboard) start_listener() { } } C.SelectionNotify { - if unsafe { event.xselection.selection == cb.selection && - event.xselection.property != C.Atom(C.None) } + if unsafe { + event.xselection.selection == cb.selection && event.xselection.property != C.Atom(C.None) + } { if unsafe { event.xselection.target == cb.get_atom(.targets) && !sent_request } { sent_request = true @@ -349,10 +354,14 @@ fn (mut cb Clipboard) start_listener() { sent_request = false to_be_requested = C.Atom(0) cb.mutex.m_lock() - prop := unsafe { read_property(event.xselection.display, event.xselection.requestor, - event.xselection.property) } - unsafe { C.XDeleteProperty(event.xselection.display, event.xselection.requestor, - event.xselection.property) } + prop := unsafe { + read_property(event.xselection.display, event.xselection.requestor, + event.xselection.property) + } + unsafe { + C.XDeleteProperty(event.xselection.display, event.xselection.requestor, + event.xselection.property) + } if cb.is_supported_target(prop.actual_type) { cb.got_text = true unsafe { @@ -369,8 +378,10 @@ fn (mut cb Clipboard) start_listener() { } } -// Helpers -// Initialize all the atoms we need +/* +* Helpers +*/ +// intern_atoms initializes all the atoms we need. fn (mut cb Clipboard) intern_atoms() { cb.atoms << C.Atom(4) // XA_ATOM cb.atoms << C.Atom(31) // XA_STRING @@ -404,7 +415,7 @@ fn read_property(d &C.Display, w C.Window, p C.Atom) Property { return Property{actual_type, actual_format, nitems, ret} } -// Finds the best target given a local copy of a property. +// pick_target finds the best target given a local copy of a property. fn (cb &Clipboard) pick_target(prop Property) C.Atom { // The list of targets is a list of atoms, so it should have type XA_ATOM // but it may have the type TARGETS instead. @@ -485,7 +496,8 @@ fn new_display() &C.Display { return C.XOpenDisplay(C.NULL) } -// create a new PRIMARY clipboard (only supported on Linux) +// new_primary returns a new X11 `PRIMARY` type `Clipboard` instance allocated on the heap. +// Please note: new_primary only works on X11 based systems. pub fn new_primary() &Clipboard { return new_x11_clipboard(.primary) }