Merge pull request #3399 from sclu1034/feature/docs

Various doc improvements nr. 4

docs/common/cursor_c.ldoc

@@ -1,80 +1,80 @@
- * <table class='widget_list' border=1>
- * <tr><td>num_glyphs          </td></tr>
- * <tr><td>cursor              </td></tr>
- * <tr><td>arrow               </td></tr>
- * <tr><td>based_arrow_down    </td></tr>
- * <tr><td>based_arrow_up      </td></tr>
- * <tr><td>boat                </td></tr>
- * <tr><td>bogosity            </td></tr>
- * <tr><td>bottom_left_corner  </td></tr>
- * <tr><td>bottom_right_corner </td></tr>
- * <tr><td>bottom_side         </td></tr>
- * <tr><td>bottom_tee          </td></tr>
- * <tr><td>box_spiral          </td></tr>
- * <tr><td>center_ptr          </td></tr>
- * <tr><td>circle              </td></tr>
- * <tr><td>clock               </td></tr>
- * <tr><td>coffee_mug          </td></tr>
- * <tr><td>cross               </td></tr>
- * <tr><td>cross_reverse       </td></tr>
- * <tr><td>crosshair           </td></tr>
- * <tr><td>diamond_cross       </td></tr>
- * <tr><td>dot                 </td></tr>
- * <tr><td>dotbox              </td></tr>
- * <tr><td>double_arrow        </td></tr>
- * <tr><td>draft_large         </td></tr>
- * <tr><td>draft_small         </td></tr>
- * <tr><td>draped_box          </td></tr>
- * <tr><td>exchange            </td></tr>
- * <tr><td>fleur               </td></tr>
- * <tr><td>gobbler             </td></tr>
- * <tr><td>gumby               </td></tr>
- * <tr><td>hand                </td></tr>
- * <tr><td>hand                </td></tr>
- * <tr><td>heart               </td></tr>
- * <tr><td>icon                </td></tr>
- * <tr><td>iron_cross          </td></tr>
- * <tr><td>left_ptr            </td></tr>
- * <tr><td>left_side           </td></tr>
- * <tr><td>left_tee            </td></tr>
- * <tr><td>leftbutton          </td></tr>
- * <tr><td>ll_angle            </td></tr>
- * <tr><td>lr_angle            </td></tr>
- * <tr><td>man                 </td></tr>
- * <tr><td>middlebutton        </td></tr>
- * <tr><td>mouse               </td></tr>
- * <tr><td>pencil              </td></tr>
- * <tr><td>pirate              </td></tr>
- * <tr><td>plus                </td></tr>
- * <tr><td>question_arrow      </td></tr>
- * <tr><td>right_ptr           </td></tr>
- * <tr><td>right_side          </td></tr>
- * <tr><td>right_tee           </td></tr>
- * <tr><td>rightbutton         </td></tr>
- * <tr><td>rtl_logo            </td></tr>
- * <tr><td>sailboat            </td></tr>
- * <tr><td>sb_down_arrow       </td></tr>
- * <tr><td>sb_h_double_arrow   </td></tr>
- * <tr><td>sb_left_arrow       </td></tr>
- * <tr><td>sb_right_arrow      </td></tr>
- * <tr><td>sb_up_arrow         </td></tr>
- * <tr><td>sb_v_double_arrow   </td></tr>
- * <tr><td>shuttle             </td></tr>
- * <tr><td>sizing              </td></tr>
- * <tr><td>spider              </td></tr>
- * <tr><td>spraycan            </td></tr>
- * <tr><td>star                </td></tr>
- * <tr><td>target              </td></tr>
- * <tr><td>tcross              </td></tr>
- * <tr><td>top_left_arrow      </td></tr>
- * <tr><td>top_left_corner     </td></tr>
- * <tr><td>top_right_corner    </td></tr>
- * <tr><td>top_side            </td></tr>
- * <tr><td>top_tee             </td></tr>
- * <tr><td>trek                </td></tr>
- * <tr><td>ul_angle            </td></tr>
- * <tr><td>umbrella            </td></tr>
- * <tr><td>ur_angle            </td></tr>
- * <tr><td>watch               </td></tr>
- * <tr><td>xterm               </td></tr>
- * </table>
+  <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>

docs/common/fixed.ldoc

@@ -1,24 +1,25 @@
---- Set a widget at a specific index, replace the current one.
+--- Set a widget at a specific index, replacing the current one.
 --
 -- @tparam number index A widget or a widget index
--- @tparam widget widget2 The widget to take the place of the first one
--- @treturn boolean If the operation is successful
+-- @tparam widget widget2 The widget to replace the previous one with
+-- @treturn boolean Returns `true` if the widget was replaced successfully,
+--   `false` otherwise.
 -- @method set
 -- @emits widget::replaced
 -- @emitstparam widget::replaced widget self The layout.
--- @emitstparam widget::replaced widget widget index The inserted widget.
+-- @emitstparam widget::replaced widget widget The inserted widget.
 -- @emitstparam widget::replaced widget previous The previous widget.
 -- @emitstparam widget::replaced number index The replaced index.
 -- @interface layout
 
 --- Replace the first instance of `widget` in the layout with `widget2`.
 --
--- **Signal:** widget::replaced The argument is the new widget and the old one
--- and the index.
 -- @tparam widget widget The widget to replace
 -- @tparam widget widget2 The widget to replace `widget` with
--- @tparam[opt=false] boolean recursive Dig in all compatible layouts to find the widget.
--- @treturn boolean If the operation is successful
+-- @tparam[opt=false] boolean recursive Recurse into all compatible layouts to
+--   find the widget.
+-- @treturn boolean Returns `true` if the widget was replaced successfully,
+--   `false` otherwise.
 -- @method replace_widget
 -- @emits widget::replaced
 -- @emitstparam widget::replaced widget self The layout.
@@ -31,35 +32,44 @@
 --
 -- @tparam number index1 The first widget index
 -- @tparam number index2 The second widget index
--- @treturn boolean If the operation is successful
+-- @treturn boolean Returns `true` if the widget was replaced successfully,
+--   `false` otherwise.
 -- @method swap
 -- @emits widget::swapped
 -- @emitstparam widget::swapped widget self The layout.
--- @emitstparam widget::swapped widget widget1 index The first widget.
--- @emitstparam widget::swapped widget widget2 index The second widget.
+-- @emitstparam widget::swapped widget widget1 The first widget.
+-- @emitstparam widget::swapped widget widget2 The second widget.
 -- @emitstparam widget::swapped number index1 The first index.
 -- @emitstparam widget::swapped number index1 The second index.
 -- @interface layout
 
 --- Swap 2 widgets in a layout.
--- If widget1 is present multiple time, only the first instance is swapped
--- **Signal:** widget::swapped The arguments are both widgets and both (new) indexes.
--- if the layouts not the same, then only `widget::replaced` will be emitted.
+--
+-- If `widget1` is present multiple time, only the first instance is swapped.
+--
+-- Calls `set` internally, so the signal `widget::replaced` is emitted for both
+-- widgets as well.
+--
 -- @tparam widget widget1 The first widget
 -- @tparam widget widget2 The second widget
--- @tparam[opt=false] boolean recursive Dig in all compatible layouts to find the widget.
--- @treturn boolean If the operation is successful
+-- @tparam[opt=false] boolean recursive Recurse into all compatible layouts to
+--   find the widget.
+-- @treturn boolean Returns `true` if the widget was replaced successfully,
+--   `false` otherwise.
 -- @method swap_widgets
 -- @emits widget::swapped
 -- @emitstparam widget::swapped widget self The layout.
--- @emitstparam widget::swapped widget widget1 index The first widget.
--- @emitstparam widget::swapped widget widget2 index The second widget.
+-- @emitstparam widget::swapped widget widget1 The first widget.
+-- @emitstparam widget::swapped widget widget2 The second widget.
 -- @emitstparam widget::swapped number index1 The first index.
 -- @emitstparam widget::swapped number index1 The second index.
 -- @interface layout
+-- @see set
 
 --- Reset the layout. This removes all widgets from the layout.
 -- @method reset
 -- @emits widget::reset
 -- @emitstparam widget::reset widget self The layout.
 -- @interface layout
+
+-- vim: filetype=lua:expandtab:shiftwidth=4:tabstop=8:softtabstop=4:textwidth=80

docs/ldoc.css

@@ -257,6 +257,23 @@ table th, table td {
     border-bottom-width: 1px;
 }
 
+.flex-list {
+    display: flex;
+    flex-wrap: wrap;
+}
+
+.flex-list > div {
+    flex-grow: 1;
+    /* Use base width based on font size
+       to make sure text fits when zooming */
+    width: 9em;
+
+    text-align: center;
+    padding: 10px;
+    margin: 5px;
+    border: 1px solid rgb(193, 204, 228);
+}
+
 #about {
     padding: 15px;
     padding-left: 16em;

lib/wibox/layout/align.lua

@@ -1,6 +1,25 @@
 ---------------------------------------------------------------------------
+-- The `align` layout has three slots for child widgets. On its main axis, it
+-- will use as much space as is available to it and distribute that to its child
+-- widgets by stretching or shrinking them based on the chosen @{expand}
+-- strategy.
+-- On its secondary axis, the biggest child widget determines the size of the
+-- layout, but smaller widgets will not be stretched to match it.
+--
+-- In its default configuration, the layout will give the first and third
+-- widgets only the minimum space they ask for and it aligns them to the outer
+-- edges. The remaining space between them is made available to the widget in
+-- slot two.
+--
+-- This layout is most commonly used to split content into left/top, center and
+-- right/bottom sections. As such, it is usually seen as the root layout in
+-- @{awful.wibar}.
+--
+-- You may also fill just one or two of the widget slots, the @{expand} algorithm
+-- will adjust accordingly.
 --
 --@DOC_wibox_layout_defaults_align_EXAMPLE@
+--
 -- @author Uli Schlachter
 -- @copyright 2010 Uli Schlachter
 -- @layoutmod wibox.layout.align
@@ -140,8 +159,10 @@ function align:layout(context, width, height)
     return result
 end
 
---- Set the layout's first widget.
--- This is the widget that is at the left/top
+--- The widget in slot one.
+--
+-- This is the widget that is at the left/top.
+--
 -- @property first
 -- @tparam widget first
 -- @propemits true false
@@ -155,7 +176,10 @@ function align:set_first(widget)
     self:emit_signal("property::first", widget)
 end
 
---- Set the layout's second widget. This is the centered one.
+--- The widget in slot two.
+--
+-- This is the centered one.
+--
 -- @property second
 -- @tparam widget second
 -- @propemits true false
@@ -169,8 +193,10 @@ function align:set_second(widget)
     self:emit_signal("property::second", widget)
 end
 
---- Set the layout's third widget.
--- This is the widget that is at the right/bottom
+--- The widget in slot three.
+--
+-- This is the widget that is at the right/bottom.
+--
 -- @property third
 -- @tparam widget third
 -- @propemits true false
@@ -227,23 +253,27 @@ function align:fit(context, orig_width, orig_height)
     return used_in_dir, used_in_other
 end
 
---- Set the expand mode which determines how sub widgets expand to take up
+--- Set the expand mode, which determines how child widgets expand to take up
 -- unused space.
 --
 -- The following values are valid:
 --
--- * "inside" - Default option. Size of outside widgets is determined using
---   their fit function. Second, middle, or center widget expands to fill
---   remaining space.
--- * "outside" - Center widget is sized using its fit function and placed in
---   the center of the allowed space. Outside widgets expand (or contract) to
---   fill remaining space on their side.
--- * "none" - All widgets are sized using their fit function, drawn to only the
---   returned space, or remaining space, whichever is smaller. Center widget
---   gets priority.
+-- * `"inside"`: The widgets in slot one and three are set to their minimal
+--   required size. The widget in slot two is then given the remaining space.
+--   This is the default behaviour.
+-- * `"outside"`: The widget in slot two is set to its minimal required size and
+--   placed in the center of the space available to the layout. The other
+--   widgets are then given the remaining space on either side.
+--   If the center widget requires all available space, the outer widgets are
+--   not drawn at all.
+-- * `"none"`: All widgets are given their minimal required size or the
+--   remaining space, whichever is smaller. The center widget gets priority.
+--
+-- Attempting to set any other value than one of those three will fall back to
+-- `"inside"`.
 --
 -- @property expand
--- @tparam[opt=inside] string mode How to use unused space.
+-- @tparam[opt="inside"] string mode How to use unused space.
 
 function align:set_expand(mode)
     if mode == "none" or mode == "outside" then
@@ -283,14 +313,16 @@ local function get_layout(dir, first, second, third)
     return ret
 end
 
---- Returns a new horizontal align layout. An align layout can display up to
--- three widgets. The widget set via :set_left() is left-aligned. :set_right()
--- sets a widget which will be right-aligned. The remaining space between those
--- two will be given to the widget set via :set_middle().
+--- Returns a new horizontal align layout.
+--
+-- The three widget slots are aligned left, center and right.
+--
+-- Additionally, this creates the aliases `set_left`, `set_middle` and
+-- `set_right` to assign @{first}, @{second} and @{third} respectively.
 -- @constructorfct wibox.layout.align.horizontal
--- @tparam[opt] widget left Widget to be put to the left.
--- @tparam[opt] widget middle Widget to be put to the middle.
--- @tparam[opt] widget right Widget to be put to the right.
+-- @tparam[opt] widget left Widget to be put in slot one.
+-- @tparam[opt] widget middle Widget to be put in slot two.
+-- @tparam[opt] widget right Widget to be put in slot three.
 function align.horizontal(left, middle, right)
     local ret = get_layout("x", left, middle, right)
 
@@ -301,14 +333,16 @@ function align.horizontal(left, middle, right)
     return ret
 end
 
---- Returns a new vertical align layout. An align layout can display up to
--- three widgets. The widget set via :set_top() is top-aligned. :set_bottom()
--- sets a widget which will be bottom-aligned. The remaining space between those
--- two will be given to the widget set via :set_middle().
+--- Returns a new vertical align layout.
+--
+-- The three widget slots are aligned top, center and bottom.
+--
+-- Additionally, this creates the aliases `set_top`, `set_middle` and
+-- `set_bottom` to assign @{first}, @{second} and @{third} respectively.
 -- @constructorfct wibox.layout.align.vertical
--- @tparam[opt] widget top Widget to be put to the top.
--- @tparam[opt] widget middle Widget to be put to the middle.
--- @tparam[opt] widget bottom Widget to be put to the right.
+-- @tparam[opt] widget top Widget to be put in slot one.
+-- @tparam[opt] widget middle Widget to be put in slot two.
+-- @tparam[opt] widget bottom Widget to be put in slot three.
 function align.vertical(top, middle, bottom)
     local ret = get_layout("y", top, middle, bottom)
 

lib/wibox/layout/fixed.lua

@@ -1,6 +1,22 @@
 ---------------------------------------------------------------------------
+-- A `fixed` layout may be initialized with any number of child widgets, and
+-- during runtime widgets may be added and removed dynamically.
+--
+-- On the main axis, child widgets are given a fixed size of exactly as much
+-- space as they ask for. The layout will then resize according to the sum of
+-- all child widgets. If the space available to the layout is not enough to
+-- include all child widgets, the excessive ones are not drawn at all.
+--
+-- Additionally, the layout allows adding empty spacing or even placing a custom
+-- spacing widget between the child widget.
+--
+-- On its secondary axis, the layout's size is determined by the largest child
+-- widget. Smaller child widgets are then placed with the same size.
+-- Therefore, child widgets may ignore their `forced_width` or `forced_height`
+-- properties for vertical and horizontal layouts respectively.
 --
 --@DOC_wibox_layout_defaults_fixed_EXAMPLE@
+--
 -- @author Uli Schlachter
 -- @copyright 2010 Uli Schlachter
 -- @layoutmod wibox.layout.fixed
@@ -32,7 +48,7 @@ function fixed:layout(context, width, height)
 
     spacing_widget = spacing ~= 0 and self._private.spacing_widget or nil
 
-    for k, v in pairs(self._private.widgets) do
+    for index, widget in pairs(self._private.widgets) do
         local w, h, local_spacing = width - x, height - y, spacing
 
         -- Some widget might be zero sized either because this is their
@@ -43,8 +59,8 @@ function fixed:layout(context, width, height)
         local zero = false
 
         if is_y then
-            if k ~= widgets_nr or not self._private.fill_space then
-                h = select(2, base.fit_widget(self, context, v, w, h))
+            if index ~= widgets_nr or not self._private.fill_space then
+                h = select(2, base.fit_widget(self, context, widget, w, h))
                 zero = h == 0
             end
 
@@ -65,8 +81,8 @@ function fixed:layout(context, width, height)
                 end
             end
         else
-            if k ~= widgets_nr or not self._private.fill_space then
-                w = select(1, base.fit_widget(self, context, v, w, h))
+            if index ~= widgets_nr or not self._private.fill_space then
+                w = select(1, base.fit_widget(self, context, widget, w, h))
                 zero = w == 0
             end
 
@@ -94,16 +110,19 @@ function fixed:layout(context, width, height)
 
         -- Place widget, even if it has zero width/height. Otherwise
         -- any layout change for zero-sized widget would become invisible.
-        table.insert(result, base.place_widget_at(v, x, y, w, h))
+        table.insert(result, base.place_widget_at(widget, x, y, w, h))
 
         x = is_x and x + w + local_spacing or x
         y = is_y and y + h + local_spacing or y
 
         -- Add the spacing widget (if needed)
-        if k < widgets_nr and spacing_widget then
+        if index < widgets_nr and spacing_widget then
             table.insert(result, base.place_widget_at(
-                spacing_widget, is_x and (x - spoffset) or x, is_y and (y - spoffset) or y,
-                is_x and abspace or w, is_y and abspace or h
+                spacing_widget,
+                is_x and (x - spoffset) or x,
+                is_y and (y - spoffset) or y,
+                is_x and abspace or w,
+                is_y and abspace or h
             ))
         end
     end
@@ -266,9 +285,13 @@ function fixed:set(index, widget2)
     return true
 end
 
---- The widget used to fill the spacing between the layout elements.
+--- A widget to insert as a separator between child widgets.
 --
--- By default, no widget is used.
+-- If this property is a valid widget and `spacing` is greater than `0`, a
+-- copy of this widget is inserted between each child widget, with its size in
+-- the layout's main direction determined by `spacing`.
+--
+-- By default no widget is used and any `spacing` is applied as an empty offset.
 --
 --@DOC_wibox_layout_fixed_spacing_widget_EXAMPLE@
 --
@@ -406,29 +429,25 @@ local function get_layout(dir, widget1, ...)
     return ret
 end
 
---- Returns a new horizontal fixed layout. Each widget will get as much space as it
--- asks for and each widget will be drawn next to its neighboring widget.
--- Widgets can be added via :add() or as arguments to this function.
--- Note that widgets ignore `forced_height`. They will use the preferred/minimum width
--- on the horizontal axis, and a stretched height on the vertical axis.
+--- Creates and returns a new horizontal fixed layout.
+--
 -- @tparam widget ... Widgets that should be added to the layout.
 -- @constructorfct wibox.layout.fixed.horizontal
 function fixed.horizontal(...)
     return get_layout("x", ...)
 end
 
---- Returns a new vertical fixed layout. Each widget will get as much space as it
--- asks for and each widget will be drawn next to its neighboring widget.
--- Widgets can be added via :add() or as arguments to this function.
--- Note that widgets ignore `forced_width`. They will use the preferred/minimum height
--- on the vertical axis, and a stretched width on the horizontal axis.
+--- Creates and returns a new vertical fixed layout.
+--
 -- @tparam widget ... Widgets that should be added to the layout.
 -- @constructorfct wibox.layout.fixed.vertical
 function fixed.vertical(...)
     return get_layout("y", ...)
 end
 
---- Add spacing between each layout widgets.
+--- The amount of space inserted between the child widgets.
+--
+-- If a `spacing_widget` is defined, this value is used for its size.
 --
 --@DOC_wibox_layout_fixed_spacing_EXAMPLE@
 --

lib/wibox/layout/flex.lua

@@ -1,4 +1,19 @@
 ---------------------------------------------------------------------------
+-- A `flex` layout may be initialized with any number of child widgets, and
+-- during runtime widgets may be added and removed dynamically.
+--
+-- On the main axis, the layout will divide the available space evenly between
+-- all child widgets, without any regard to how much space these widgets might
+-- be asking for.
+--
+-- Just like @{wibox.layout.fixed}, `flex` allows adding spacing between the
+-- widgets, either as an ofset via @{spacing} or with a
+-- @{spacing_widget}.
+--
+-- On its secondary axis, the layout's size is determined by the largest child
+-- widget. Smaller child widgets are then placed with the same size.
+-- Therefore, child widgets may ignore their `forced_width` or `forced_height`
+-- properties for vertical and horizontal layouts respectively.
 --
 --@DOC_wibox_layout_defaults_flex_EXAMPLE@
 -- @author Uli Schlachter
@@ -56,14 +71,18 @@ local flex = {}
 -- @treturn boolean If the operation is successful
 -- @method insert
 -- @emits widget::inserted
--- @emitstparam widget::inserted widget self The fixed layout.
--- @emitstparam widget::inserted widget widget index The inserted widget.
+-- @emitstparam widget::inserted widget self The layout.
+-- @emitstparam widget::inserted widget widget The inserted widget.
 -- @emitstparam widget::inserted number count The widget count.
 -- @interface layout
 
---- The widget used to fill the spacing between the layout elements.
+--- A widget to insert as a separator between child widgets.
 --
--- By default, no widget is used.
+-- If this property is a valid widget and @{spacing} is greater than `0`, a
+-- copy of this widget is inserted between each child widget, with its size in
+-- the layout's main direction determined by @{spacing}.
+--
+-- By default no widget is used and any @{spacing} is applied as an empty offset.
 --
 --@DOC_wibox_layout_flex_spacing_widget_EXAMPLE@
 --
@@ -72,13 +91,16 @@ local flex = {}
 -- @propemits true false
 -- @interface layout
 
---- Add spacing between each layout widgets.
+--- The amount of space inserted between the child widgets.
+--
+-- If a @{spacing_widget} is defined, this value is used for its size.
 --
 --@DOC_wibox_layout_flex_spacing_EXAMPLE@
 --
 -- @property spacing
 -- @tparam number spacing Spacing between widgets.
 -- @propemits true false
+-- @interface layout
 
 function flex:layout(_, width, height)
     local result = {}
@@ -195,10 +217,7 @@ local function get_layout(dir, widget1, ...)
     return ret
 end
 
---- Returns a new horizontal flex layout.
---
--- A flex layout shares the available space.
--- equally among all widgets. Widgets can be added via `:add(widget)`.
+--- Creates and returns a new horizontal flex layout.
 --
 -- @tparam widget ... Widgets that should be added to the layout.
 -- @constructorfct wibox.layout.flex.horizontal
@@ -206,10 +225,7 @@ function flex.horizontal(...)
     return get_layout("horizontal", ...)
 end
 
---- Returns a new vertical flex layout.
---
--- A flex layout shares the available space
--- equally among all widgets. Widgets can be added via `:add(widget)`.
+--- Creates and returns a new vertical flex layout.
 --
 -- @tparam widget ... Widgets that should be added to the layout.
 -- @constructorfct wibox.layout.flex.vertical

lib/wibox/widget/imagebox.lua

@@ -1,20 +1,20 @@
 ---------------------------------------------------------------------------
--- A widget to display image.
+-- A widget to display an image.
 --
--- The `wibox.widget.imagebox` is part of the Awesome WM's wiboxes system
+-- The `wibox.widget.imagebox` is part of the Awesome WM's widget system
 -- (see @{03-declarative-layout.md}).
 --
 -- This widget displays an image. The image can be a file,
 -- a cairo image surface, or an rsvg handle object (see the
 -- [image property](#image)).
 --
--- Use a `wibox.widget.imagebox`
+-- Examples using a `wibox.widget.imagebox`:
 -- ---
 --
 -- @DOC_wibox_widget_defaults_imagebox_EXAMPLE@
 --
 -- Alternatively, you can declare the `imagebox` widget using the
--- declarative pattern (Both codes are strictly equivalent):
+-- declarative pattern (both variants are strictly equivalent):
 --
 -- @DOC_wibox_widget_declarative-pattern_imagebox_EXAMPLE@
 --
@@ -219,15 +219,14 @@ end
 --
 -- It can can be any of the following:
 --
--- * A `string` : Interpreted as the path to an image file,
--- * A cairo image surface : Directly used as is,
--- * An rsvg handle object : Directly used as is,
--- * `nil` : Unset the image.
+-- * A `string`: Interpreted as a path to an image file
+-- * A cairo image surface: Directly used as-is
+-- * A librsvg handle object: Directly used as-is
+-- * `nil`: Unset the image.
 --
 -- @property image
 -- @tparam image image The image to render.
 -- @propemits false false
--- @see set_image
 
 --- Set the `imagebox` image.
 --
@@ -281,8 +280,9 @@ function imagebox:set_image(image)
 end
 
 --- Set a clip shape for this imagebox.
--- A clip shape define an area where the content is displayed and one where it
--- is trimmed.
+--
+-- A clip shape defines an area and dimension to which the content should be
+-- trimmed.
 --
 -- @DOC_wibox_widget_imagebox_clip_shape_EXAMPLE@
 --
@@ -290,13 +290,13 @@ end
 -- @tparam function|gears.shape clip_shape A `gears.shape` compatible shape function.
 -- @propemits true false
 -- @see gears.shape
--- @see set_clip_shape
 
 --- Set a clip shape for this imagebox.
--- A clip shape define an area where the content is displayed and one where it
--- is trimmed.
 --
--- Any other parameters will be passed to the clip shape function.
+-- A clip shape defines an area and dimensions to which the content should be
+-- trimmed.
+--
+-- Additional parameters will be passed to the clip shape function.
 --
 -- @tparam function|gears.shape clip_shape A `gears_shape` compatible shape function.
 -- @method set_clip_shape
@@ -330,35 +330,38 @@ end
 
 --- Set the horizontal fit policy.
 --
--- Values are:
+-- Valid values are:
 --
---  * **auto**: Honor the `resize` varible and preserve the aspect ratio (default).
---  * **none**: Do not resize at all.
---  * **fit**: Resize to the widget width.
+--  * `"auto"`: Honor the `resize` variable and preserve the aspect ratio.
+--   This is the default behaviour.
+--  * `"none"`: Do not resize at all.
+--  * `"fit"`: Resize to the widget width.
 --
 -- Here is the result for a 22x32 image:
 --
 -- @DOC_wibox_widget_imagebox_horizontal_fit_policy_EXAMPLE@
 --
 -- @property horizontal_fit_policy
---  @tparam[opt=auto] string horizontal_fit_policy
+-- @tparam[opt="auto"] string horizontal_fit_policy
 -- @propemits true false
 -- @see vertical_fit_policy
 -- @see resize
 
 --- Set the vertical fit policy.
--- Values are:
 --
---  * **auto**: Honor the `resize` varible and preserve the aspect ratio (default).
---  * **none**: Do not resize at all.
---  * **fit**: Resize to the widget height.
+-- Valid values are:
+--
+--  * `"auto"`: Honor the `resize` varible and preserve the aspect ratio.
+--   This is the default behaviour.
+--  * `"none"`: Do not resize at all.
+--  * `"fit"`: Resize to the widget height.
 --
 -- Here is the result for a 32x22 image:
 --
 -- @DOC_wibox_widget_imagebox_vertical_fit_policy_EXAMPLE@
 --
 -- @property vertical_fit_policy
--- @tparam[opt=auto] string horizontal_fit_policy
+-- @tparam[opt="auto"] string horizontal_fit_policy
 -- @propemits true false
 -- @see horizontal_fit_policy
 -- @see resize
@@ -368,14 +371,14 @@ end
 --
 -- Possible values are:
 --
--- * *top*
--- * *center* (default)
--- * *bottom*
+-- * `"top"`
+-- * `"center"` (default)
+-- * `"bottom"`
 --
 -- @DOC_wibox_widget_imagebox_valign_EXAMPLE@
 --
 -- @property valign
--- @tparam string avlign
+-- @tparam[opt="center"] string valign
 -- @propemits true false
 -- @see wibox.container.place
 -- @see halign
@@ -384,14 +387,14 @@ end
 --
 -- Possible values are:
 --
--- * *left*
--- * *center* (default)
--- * *right*
+-- * `"left"`
+-- * `"center"` (default)
+-- * `"right"`
 --
 -- @DOC_wibox_widget_imagebox_halign_EXAMPLE@
 --
 -- @property halign
--- @tparam string halign
+-- @tparam[opt="center"] string halign
 -- @propemits true false
 -- @see wibox.container.place
 -- @see valign
@@ -399,8 +402,9 @@ end
 --- The maximum scaling factor.
 --
 -- If an image is scaled too much, it gets very blurry. This
--- property allows to limit the scaling. Use the `valign` and
--- `halign` to control how the image will be aligned.
+-- property allows to limit the scaling.
+-- Use the properties `valign` and `halign` to control how the image will be
+-- aligned.
 --
 -- In the example below, the original size is 22x22
 --
@@ -432,13 +436,15 @@ end
 -- <tr><td>bilinear</td><td>Linear interpolation in two dimensions</td></tr>
 --</table>
 --
--- The image used in the example below has a resolution of 32x22 and is intentionally
--- blocky to highlight the difference. It is zoomed by a factor of 3.
+-- The image used in the example below has a resolution of 32x22 and is
+-- intentionally blocky to highlight the difference.
+-- It is zoomed by a factor of 3.
 --
 -- @DOC_wibox_widget_imagebox_scaling_quality_EXAMPLE@
 --
 -- @property scaling_quality
--- @tparam string scaling_quality Either `fast`, `good`, `best`, `nearest` or `bilinear`.
+-- @tparam string scaling_quality Either `"fast"`, `"good"`, `"best"`,
+--   `"nearest"` or `"bilinear"`.
 -- @propemits true false
 -- @see resize
 -- @see horizontal_fit_policy

lib/wibox/widget/textbox.lua

@@ -222,17 +222,22 @@ function textbox:get_text()
     return self._private.layout.text
 end
 
---- Set a textbox ellipsize mode.
+--- Set the text ellipsize mode.
 --
 -- Valid values are:
 --
--- * **start**
--- * **middle**
--- * **end**
+-- * `"start"`
+-- * `"middle"`
+-- * `"end"`
+-- * `"none"`
+--
+-- See Pango for additional details:
+-- [Layout.set_ellipsize](https://docs.gtk.org/Pango/method.Layout.set_ellipsize.html)
+--
+--@DOC_wibox_widget_textbox_ellipsize_EXAMPLE@
 --
 -- @property ellipsize
--- @tparam string mode Where should long lines be shortened? "start", "middle"
---  or "end".
+-- @tparam string mode The ellipsize mode.
 -- @propemits true false
 
 function textbox:set_ellipsize(mode)

mousegrabber.c

@@ -82,7 +82,7 @@ mousegrabber_handleevent(lua_State *L, int x, int y, uint16_t mask)
  * The function is called with one argument:
  * a table containing modifiers pointer coordinates.
  *
- * The list of valid cusrors are:
+ * The list of valid cursors is:
  *
  *@DOC_cursor_c_COMMON@
  *

tests/examples/wibox/container/defaults/radialprogressbar.lua

@@ -1,4 +1,4 @@
---DOC_HIDE_ALL
+--DOC_HIDE_START
 --DOC_GEN_IMAGE
 local wibox = require("wibox")
 
@@ -9,6 +9,7 @@ return {
     widget = wibox.widget.textbox,
 },
 {
+--DOC_HIDE_END
     {
         {
             text   = "After",
@@ -21,8 +22,9 @@ return {
         min_value = 0,
         widget    = wibox.container.radialprogressbar
     },
+--DOC_HIDE_START
     margins = 5,
     layout = wibox.container.margin
 }
 
---DOC_HIDE vim: filetype=lua:expandtab:shiftwidth=4:tabstop=8:softtabstop=4:textwidth=80
+-- vim: filetype=lua:expandtab:shiftwidth=4:tabstop=8:softtabstop=4:textwidth=80

tests/examples/wibox/widget/textbox/ellipsize.lua

@@ -0,0 +1,59 @@
+--DOC_GEN_IMAGE --DOC_HIDE
+
+--DOC_HIDE_START
+local parent = ...
+local wibox  = require("wibox")
+
+local widget = function(inner)
+    return wibox.widget {
+        {
+            {
+                inner,
+                margins = 5,
+                widget = wibox.container.margin,
+            },
+            border_width = 2,
+            widget = wibox.container.background,
+        },
+        strategy = "max",
+        height = 25,
+        widget = wibox.container.constraint,
+    }
+end
+
+local widgets = {
+--DOC_HIDE_END
+
+widget{
+    text = "This is a very long text, that cannot be displayed fully.",
+    ellipsize = "start",
+    widget = wibox.widget.textbox,
+},
+
+widget{
+    text = "This is a very long text, that cannot be displayed fully.",
+    ellipsize = "end",
+    widget = wibox.widget.textbox,
+},
+
+widget{
+    text = "This is a very long text, that cannot be displayed fully.",
+    ellipsize = "middle",
+    widget = wibox.widget.textbox,
+},
+
+widget{
+    text = "This is a very long text, that cannot be displayed fully.",
+    ellipsize = "none",
+    valign = "top",
+    widget = wibox.widget.textbox,
+}
+
+--DOC_HIDE_START
+}
+
+parent:set_children(widgets)
+
+return parent:fit({ dpi = 96 }, 150, 200)
+
+-- vim: filetype=lua:expandtab:shiftwidth=4:tabstop=8:softtabstop=4:textwidth=80