Merge pull request #3529 from sclu1034/feature/docs

Various docs improvements

docs/common/cursor_c.ldoc

@@ -1,30 +1,30 @@
   <div class='flex-list'>
- * <div>num_glyphs</div>
+ * <div>num\_glyphs</div>
  * <div>arrow</div>
- * <div>based_arrow_down</div>
- * <div>based_arrow_up</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>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>coffee\_mug</div>
  * <div>cross</div>
  * <div>crosshair</div>
- * <div>cross_reverse</div>
+ * <div>cross\_reverse</div>
  * <div>cursor</div>
- * <div>diamond_cross</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>double\_arrow</div>
+ * <div>draft\_large</div>
+ * <div>draft\_small</div>
+ * <div>draped\_box</div>
  * <div>exchange</div>
  * <div>fleur</div>
  * <div>gobbler</div>
@@ -33,32 +33,32 @@
  * <div>hand</div>
  * <div>heart</div>
  * <div>icon</div>
- * <div>iron_cross</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>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>question\_arrow</div>
  * <div>rightbutton</div>
- * <div>right_ptr</div>
- * <div>right_side</div>
- * <div>right_tee</div>
- * <div>rtl_logo</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>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>
@@ -66,15 +66,15 @@
  * <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>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>ul\_angle</div>
  * <div>umbrella</div>
- * <div>ur_angle</div>
+ * <div>ur\_angle</div>
  * <div>watch</div>
  * <div>xterm</div>
  * </div>

docs/common/rule.ldoc

@@ -4,15 +4,17 @@
 --
 -- @rulecomponent properties
 -- @param table
--- @see callbacks
+-- @see callback
 
 --TODO add ^
 -- @DOC_text_gears_matcher_properties_EXAMPLE@
 
---- A list of callback function to call *after* the properties have been apploed.
--- @rulecomponent callbacks
--- @param table
--- @see properties
+--- A callback function to call *after* the `properties` have been applied.
+--
+-- The callback is called with the current client as first argument.
+--
+-- @rulecomponent callback
+-- @param function
 
 --- A table whose content will be compared to the target object current properties.
 --

docs/ldoc.css

@@ -47,7 +47,11 @@ p.name {
     font-family: monospace;
 }
 
-kbd, p code, ol code {
+kbd,
+p code,
+ol code,
+ul code,
+dd > code {
     background-color: #eaedf587;
     padding-left: 3px;
     padding-right: 3px;

docs/ldoc.ltp

@@ -395,7 +395,7 @@
 #       if def == true then
          (<em>optional</em>)
 #      elseif def then
-         (<em>default</em> $(def))
+         (<em>default</em> <code>$(def)</code>)
 #       end
 #       if item:readonly(p) then
           <em>readonly</em>
@@ -535,7 +535,6 @@
 </div> <!-- id="main" -->
 <div id="about">
 <i>generated by <a href="http://github.com/stevedonovan/LDoc">LDoc $(ldoc.version)</a></i>
-<i style="float:right;">Last updated $(ldoc.updatetime) </i>
 </div> <!-- id="about" -->
 </div> <!-- id="container" -->
 </body>

lib/gears/timer.lua

@@ -63,22 +63,27 @@ local protected_call = require("gears.protected_call")
 local gdebug = require("gears.debug")
 
 --- Timer objects. This type of object is useful when triggering events repeatedly.
+--
 -- The timer will emit the "timeout" signal every N seconds, N being the timeout
 -- value. Note that a started timer will not be garbage collected. Call `:stop`
--- to enable garbage collection.
+-- before dropping the last reference to prevent leaking the object.
+--
 -- @tfield number timeout Interval in seconds to emit the timeout signal.
---   Can be any value, including floating point ones (e.g. 1.5 seconds).
+--   Can be any value, including floating point ones (e.g. `1.5` seconds).
 -- @tfield boolean started Read-only boolean field indicating if the timer has been
 --   started.
 -- @table timer
 
---- When the timer is started.
+--- Emitted when the timer is started.
 -- @signal start
 
---- When the timer is stopped.
+--- Emitted when the timer is stopped.
 -- @signal stop
 
---- When the timer had a timeout event.
+--- Emitted when `timeout` seconds have elapsed.
+--
+-- This will be emitted repeatedly, unless `single_shot` has been set to `true`
+-- for the timer.
 -- @signal timeout
 
 local timer = { mt = {} }
@@ -156,11 +161,18 @@ local timer_instance_mt = {
 }
 
 --- Create a new timer object.
+--
+-- `call_now` only takes effect when a `callback` is provided. `single_shot`,
+-- on the other hand, also stops signals connected to the `timeout` signal.
+--
+-- Specifying a function `func` as `args.callback` is equivalent to calling
+-- `:connect_signal(func)` on the timer object.
+--
 -- @tparam table args Arguments.
--- @tparam number args.timeout Timeout in seconds (e.g. 1.5).
+-- @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=nil] function args.callback Callback function to connect to the
+-- @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.
 -- @treturn timer

lib/wibox/widget/textbox.lua

@@ -301,19 +301,21 @@ function textbox:set_wrap(mode)
     end
 end
 
---- The textbox' vertical alignment.
+--- The vertical text alignment.
+--
+-- This aligns the text within the widget's bounds. In some situations this may
+-- differ from aligning the widget with `wibox.container.place`.
 --
 -- Valid values are:
 --
--- * **top**
--- * **center**
--- * **bottom**
+-- * `"top"`
+-- * `"center"`
+-- * `"bottom"`
 --
 --@DOC_wibox_widget_textbox_valign1_EXAMPLE@
 --
 -- @property valign
--- @tparam[opt="center"] string mode Where should the textbox be drawn? "top", "center" or
---  "bottom".
+-- @tparam[opt="center"] string mode The vertical alignment
 -- @propemits true false
 
 function textbox:set_valign(mode)
@@ -329,19 +331,21 @@ function textbox:set_valign(mode)
     end
 end
 
---- Set a textbox horizontal alignment.
+--- The horizontal text alignment.
+--
+-- This aligns the text within the widget's bounds. In some situations this may
+-- differ from aligning the widget with `wibox.container.place`.
 --
 -- Valid values are:
 --
--- * **left**
--- * **center**
--- * **right**
+-- * `"left"`
+-- * `"center"`
+-- * `"right"`
 --
 --@DOC_wibox_widget_textbox_align1_EXAMPLE@
 --
 -- @property align
--- @tparam[opt="left"] string mode Where should the textbox be drawn? "left", "center" or
---  "right".
+-- @tparam[opt="left"] string mode The horizontal alignment
 -- @propemits true false
 
 function textbox:set_align(mode)

tests/examples/wibox/widget/defaults/slider.lua

@@ -1,12 +1,12 @@
---DOC_GEN_IMAGE --DOC_HIDE
-local parent    = ... --DOC_HIDE
-local wibox     = require( "wibox"     ) --DOC_HIDE
-local beautiful = require( "beautiful" ) --DOC_HIDE
-local gears     = {shape=require("gears.shape") } --DOC_HIDE
+--DOC_GEN_IMAGE --DOC_HIDE_START
+local parent    = ...
+local wibox     = require( "wibox"     )
+local beautiful = require( "beautiful" )
+local gears     = {shape=require("gears.shape") }
+local naughty = { notify = function(_) end }
 
-parent:add( --DOC_HIDE
-
-wibox.widget {
+--DOC_HIDE_END
+local widget = wibox.widget {
     bar_shape           = gears.shape.rounded_rect,
     bar_height          = 3,
     bar_color           = beautiful.border_color,
@@ -19,6 +19,19 @@ wibox.widget {
     forced_height = 50, --DOC_HIDE
     forced_width  = 100, --DOC_HIDE
 }
+--DOC_NEWLINE
+-- Connect to `property::value` to use the value on change
+widget:connect_signal("property::value", function(_, new_value)
+    --DOC_HIDE_START
+    if new_value ~= 10 then
+        error(string.format("unexpected value %s", new_value))
+    end
+    --DOC_HIDE_END
+    naughty.notify { title = "Slider changed", message = new_value }
+end)
 
-) --DOC_HIDE
---DOC_HIDE vim: filetype=lua:expandtab:shiftwidth=4:tabstop=8:softtabstop=4:textwidth=80
+--DOC_HIDE_START
+widget.value = 10
+parent:add(widget)
+
+-- vim: filetype=lua:expandtab:shiftwidth=4:tabstop=8:softtabstop=4:textwidth=80