From 03285e8589b5fe2ed6a7dc74fd754db3685116d1 Mon Sep 17 00:00:00 2001
From: Aidin <149610592+aidinio@users.noreply.github.com>
Date: Thu, 5 Sep 2024 17:57:43 +0330
Subject: [PATCH] Comment and documentation improvement (#3943)

* Added that the timer timeout is in seconds

* Contrasted the differences of autostart and call_now

* A minor grammatical change

* Spread comments in multiple lines so lines would be shorter

* Used three dashes instead of one for documentation

* Included available cursor names as an ldoc files, and also added
a new file named 'cursor_c_lua.ldoc' which uses awesome comments
syntax, because the existing 'cursor_c.ldoc' could not be compiled.

* Fixed typo

* Fixed formatting and file names
---
 docs/common/cursor.ldoc        | 80 ++++++++++++++++++++++++++++++++++
 lib/gears/timer.lua            |  6 +--
 lib/wibox/widget/graph.lua     |  6 +--
 lib/wibox/widget/separator.lua |  2 +-
 lib/wibox/widget/slider.lua    | 15 +++++--
 5 files changed, 99 insertions(+), 10 deletions(-)
 create mode 100644 docs/common/cursor.ldoc

diff --git a/docs/common/cursor.ldoc b/docs/common/cursor.ldoc
new file mode 100644
index 000000000..8401b2e45
--- /dev/null
+++ b/docs/common/cursor.ldoc
@@ -0,0 +1,80 @@
+ <div class='flex-list'>
+-- <div>num\_glyphs</div>
+-- <div>arrow</div>
+-- <div>based\_arrow\_down</div>
+-- <div>based\_arrow\_up</div>
+-- <div>boat</div>
+-- <div>bogosity</div>
+-- <div>bottom\_left\_corner</div>
+-- <div>bottom\_right\_corner</div>
+-- <div>bottom\_side</div>
+-- <div>bottom\_tee</div>
+-- <div>box\_spiral</div>
+-- <div>center\_ptr</div>
+-- <div>circle</div>
+-- <div>clock</div>
+-- <div>coffee\_mug</div>
+-- <div>cross</div>
+-- <div>crosshair</div>
+-- <div>cross\_reverse</div>
+-- <div>cursor</div>
+-- <div>diamond\_cross</div>
+-- <div>dotbox</div>
+-- <div>dot</div>
+-- <div>double\_arrow</div>
+-- <div>draft\_large</div>
+-- <div>draft\_small</div>
+-- <div>draped\_box</div>
+-- <div>exchange</div>
+-- <div>fleur</div>
+-- <div>gobbler</div>
+-- <div>gumby</div>
+-- <div>hand</div>
+-- <div>hand</div>
+-- <div>heart</div>
+-- <div>icon</div>
+-- <div>iron\_cross</div>
+-- <div>leftbutton</div>
+-- <div>left\_ptr</div>
+-- <div>left\_side</div>
+-- <div>left\_tee</div>
+-- <div>ll\_angle</div>
+-- <div>lr\_angle</div>
+-- <div>man</div>
+-- <div>middlebutton</div>
+-- <div>mouse</div>
+-- <div>pencil</div>
+-- <div>pirate</div>
+-- <div>plus</div>
+-- <div>question\_arrow</div>
+-- <div>rightbutton</div>
+-- <div>right\_ptr</div>
+-- <div>right\_side</div>
+-- <div>right\_tee</div>
+-- <div>rtl\_logo</div>
+-- <div>sailboat</div>
+-- <div>sb\_down\_arrow</div>
+-- <div>sb\_h\_double\_arrow</div>
+-- <div>sb\_left\_arrow</div>
+-- <div>sb\_right\_arrow</div>
+-- <div>sb\_up\_arrow</div>
+-- <div>sb\_v\_double\_arrow</div>
+-- <div>shuttle</div>
+-- <div>sizing</div>
+-- <div>spider</div>
+-- <div>spraycan</div>
+-- <div>star</div>
+-- <div>target</div>
+-- <div>tcross</div>
+-- <div>top\_left\_arrow</div>
+-- <div>top\_left\_corner</div>
+-- <div>top\_right\_corner</div>
+-- <div>top\_side</div>
+-- <div>top\_tee</div>
+-- <div>trek</div>
+-- <div>ul\_angle</div>
+-- <div>umbrella</div>
+-- <div>ur\_angle</div>
+-- <div>watch</div>
+-- <div>xterm</div>
+-- </div>
diff --git a/lib/gears/timer.lua b/lib/gears/timer.lua
index 5606b87a4..28045292d 100644
--- a/lib/gears/timer.lua
+++ b/lib/gears/timer.lua
@@ -145,7 +145,7 @@ end
 -- @see start
 -- @see stop
 
---- The timer timeout value.
+--- The timer timeout value in seconds.
 --
 -- @property timeout
 -- @tparam[opt=0] number timeout
@@ -182,8 +182,8 @@ local timer_instance_mt = {
 --
 -- @tparam table args Arguments.
 -- @tparam number args.timeout Timeout in seconds (e.g. `1.5`).
--- @tparam[opt=false] boolean args.autostart Automatically start the timer.
--- @tparam[opt=false] boolean args.call_now Call the callback at timer creation.
+-- @tparam[opt=false] boolean args.autostart Immediately start the timer countdown.
+-- @tparam[opt=false] boolean args.call_now Immediately call the callback function.
 -- @tparam[opt] function args.callback Callback function to connect to the
 --  "timeout" signal.
 -- @tparam[opt=false] boolean args.single_shot Run only once then stop.
diff --git a/lib/wibox/widget/graph.lua b/lib/wibox/widget/graph.lua
index 96fa3d2e5..9982dbbd5 100644
--- a/lib/wibox/widget/graph.lua
+++ b/lib/wibox/widget/graph.lua
@@ -1,9 +1,9 @@
 ---------------------------------------------------------------------------
 --- Display multiple values as a stream of bars.
 --
--- The graph goes from left to right. To change this to right to left, use
--- a `wibox.container.mirror` widget. This can also be used to have data
--- shown from top to bottom.
+-- The graph goes from left to right. To change the movement's direction,
+-- use a `wibox.container.mirror` widget. This can also be used to have
+-- data shown from top to bottom.
 --
 -- To add text on top of the graph, use a `wibox.layout.stack` and a
 -- `wibox.container.align` widgets.
diff --git a/lib/wibox/widget/separator.lua b/lib/wibox/widget/separator.lua
index 3d13cb881..32f44e5ae 100644
--- a/lib/wibox/widget/separator.lua
+++ b/lib/wibox/widget/separator.lua
@@ -1,7 +1,7 @@
 ---------------------------------------------------------------------------
 -- A flexible separator widget.
 --
--- By default, this widget display a simple line, but can be extended by themes
+-- By default, this widget displays a simple line, but can be extended by themes
 -- (or directly) to display much more complex visuals.
 --
 -- This widget is mainly intended to be used alongside the `spacing_widget`
diff --git a/lib/wibox/widget/slider.lua b/lib/wibox/widget/slider.lua
index 690ee7fad..dedc45415 100644
--- a/lib/wibox/widget/slider.lua
+++ b/lib/wibox/widget/slider.lua
@@ -89,7 +89,11 @@ local slider = {mt={}}
 -- @propemits true false
 -- @propbeautiful
 
---- The handle grab cursor.
+--- The cursor icon while grabbing the handle.
+-- The available cursor names are:
+--
+--@DOC_cursor_COMMON@
+--
 -- @property handle_cursor
 -- @tparam[opt="fleur"] string|nil handle_cursor
 -- @propbeautiful
@@ -228,7 +232,10 @@ local slider = {mt={}}
 -- @tparam[opt=gears.shape.rectangle] gears.shape shape
 -- @see gears.shape
 
---- The handle grab cursor.
+--- The cursor icon while grabbing the handle.
+-- The available cursor names are:
+--
+--@DOC_cursor_COMMON@
 --
 -- @beautiful beautiful.slider_handle_cursor
 -- @tparam[opt="fleur"] string cursor
@@ -565,7 +572,9 @@ end
 -- @tparam[opt] number args.handle_width The slider handle width.
 -- @tparam[opt] color args.handle_border_color The handle border_color.
 -- @tparam[opt] number args.handle_border_width The handle border width.
--- @tparam[opt] string args.handle_cursor The handle grab cursor.
+-- @tparam[opt] string args.handle_cursor
+--   The cursor icon while grabbing the handle.
+--   The available cursor names are listed under handle_cursor, in the "Object properties" section.
 -- @tparam[opt] gears.shape args.bar_shape The bar (background) shape.
 -- @tparam[opt] number args.bar_height The bar (background) height.
 -- @tparam[opt] color args.bar_color The bar (background) color.