Merge branch 'doc_shared' of https://github.com/Elv13/awesome-1

awesomeConfig.cmake

@@ -297,6 +297,9 @@ set(AWESOME_THEMES_PATH      ${AWESOME_DATA_PATH}/themes)
 
 
 if(GENERATE_DOC)
+    # Load the common documentation
+    include(docs/load_ldoc.cmake)
+
     # Generate some images and examples
     include(docs/generate_examples.cmake)
 

docs/common/fixed.ldoc

@@ -0,0 +1,41 @@
+--- Set a widget at a specific index, replace the current one
+-- @tparam number index A widget or a widget index
+-- @param widget2 The widget to take the place of the first one
+-- @treturn boolean If the operation is successful
+-- @name set
+-- @class function
+
+--- Replace the first instance of `widget` in the layout with `widget2`
+-- @param widget The widget to replace
+-- @param widget2 The widget to replace `widget` with
+-- @tparam[opt=false] boolean recursive Digg in all compatible layouts to find the widget.
+-- @treturn boolean If the operation is successful
+-- @name replace_widget
+-- @class function
+
+--- Swap 2 widgets in a layout
+-- @tparam number index1 The first widget index
+-- @tparam number index2 The second widget index
+-- @treturn boolean If the operation is successful
+-- @name swap
+-- @class function
+
+--- Swap 2 widgets in a layout
+-- If widget1 is present multiple time, only the first instance is swapped
+-- @param widget1 The first widget
+-- @param widget2 The second widget
+-- @tparam[opt=false] boolean recursive Digg in all compatible layouts to find the widget.
+-- @treturn boolean If the operation is successful
+-- @name swap_widgets
+-- @class function
+
+--- Get all children of this layout.
+-- @param layout The layout you are modifying.
+-- @return a list of all widgets
+-- @name get_children
+-- @class function
+
+--- Reset a ratio layout. This removes all widgets from the layout.
+-- @param layout The layout you are modifying.
+-- @name reset
+-- @class function

docs/load_ldoc.cmake

@@ -0,0 +1,18 @@
+# To avoid copy pasting, some documentation is stored in reusable files
+set(SHAPE_FILE "${SOURCE_DIR}/docs/common/${SHAPE_NAME}.lua")
+
+set(path "${SOURCE_DIR}/docs/common/")
+
+# Get the documentation file list
+file(GLOB doc_files RELATIVE "${path}" "${path}/*.ldoc")
+
+foreach(doc_file_name ${doc_files})
+    # Read the file
+    file(READ "${path}/${doc_file_name}" doc_file_content)
+
+    # Remove the file extension
+    string(REGEX REPLACE "\\.ldoc" "" DOC_FILE_NAME ${doc_file_name})
+
+    # Create a new variable usable from lua files
+    set(DOC_${DOC_FILE_NAME}_COMMON "Imported documentation\n\n${doc_file_content}")
+endforeach()

lib/wibox/layout/fixed.lua

@@ -13,7 +13,9 @@ local util = require("awful.util")
 
 local fixed = {}
 
---- Layout a fixed layout. Each widget gets just the space it asks for.
+--@DOC_fixed_COMMON@
+
+-- Layout a fixed layout. Each widget gets just the space it asks for.
 -- @param context The context in which we are drawn.
 -- @param width The available width.
 -- @param height The available height.
@@ -133,10 +135,6 @@ function fixed:replace_widget(widget, widget2, recursive)
     return false
 end
 
---- Swap 2 widgets in a layout
--- @tparam number index1 The first widget index
--- @tparam number index2 The second widget index
--- @treturn boolean If the operation is successful
 function fixed:swap(index1, index2)
     if not index1 or not index2 or index1 > #self.widgets
         or index2 > #self.widgets then
@@ -151,12 +149,6 @@ function fixed:swap(index1, index2)
     return true
 end
 
---- Swap 2 widgets in a layout
--- If widget1 is present multiple time, only the first instance is swapped
--- @param widget1 The first widget
--- @param widget2 The second widget
--- @tparam[opt=false] boolean recursive Digg in all compatible layouts to find the widget.
--- @treturn boolean If the operation is successful
 function fixed:swap_widgets(widget1, widget2, recursive)
     base.check_widget(widget1)
     base.check_widget(widget2)
@@ -182,10 +174,6 @@ function fixed:swap_widgets(widget1, widget2, recursive)
     return false
 end
 
---- Set a widget at a specific index, replace the current one
--- @tparam number index A widget or a widget index
--- @param widget2 The widget to take the place of the first one
--- @treturn boolean If the operation is successful
 function fixed:set(index, widget2)
     if (not widget2) or (not self.widgets[index]) then return false end
 
@@ -212,7 +200,7 @@ function fixed:insert(index, widget)
     return true
 end
 
---- Fit the fixed layout into the given space
+-- Fit the fixed layout into the given space
 -- @param context The context in which we are fit.
 -- @param orig_width The available width.
 -- @param orig_height The available height.
@@ -253,7 +241,6 @@ function fixed:fit(context, orig_width, orig_height)
     return used_in_dir + spacing, used_max
 end
 
---- Reset a fixed layout. This removes all widgets from the layout.
 function fixed:reset()
     self.widgets = {}
     self:emit_signal("widget::layout_changed")
@@ -290,6 +277,7 @@ end
 -- 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.
 -- @tparam widget ... Widgets that should be added to the layout.
+-- @function wibox.layout.fixed.horizontal
 function fixed.horizontal(...)
     return get_layout("x", ...)
 end
@@ -298,6 +286,7 @@ end
 -- 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.
 -- @tparam widget ... Widgets that should be added to the layout.
+-- @function wibox.layout.fixed.vertical
 function fixed.vertical(...)
     return get_layout("y", ...)
 end

lib/wibox/layout/flex.lua

@@ -14,22 +14,7 @@ local util = require("awful.util")
 
 local flex = {}
 
---- Layout a fixed layout. Each widget gets just the space it asks for.
--- @param layout The layout you are modifying.
--- @param context The context in which we are drawn.
--- @param width The available width.
--- @param height The available height.
--- @name layout
--- @class function
-
---- Get all children of this layout
--- @param layout The layout you are modifying.
--- @warning If the widget contain itself and recursive is true, this will cause
---   a stack overflow
--- @param[opt] recursive Also add all widgets of childrens
--- @return a list of all widgets
--- @name get_children
--- @class function
+--@DOC_fixed_COMMON@
 
 --- Replace the layout children
 -- @tparam table children A table composed of valid widgets
@@ -42,13 +27,6 @@ local flex = {}
 -- @name add
 -- @class function
 
---- Set a widget at a specific index, replace the current one
--- @tparam number index A widget or a widget index
--- @param widget2 The widget to take the place of the first one
--- @treturn boolean If the operation is successful
--- @name set
--- @class function
-
 --- Remove a widget from the layout
 -- @tparam index The widget index to remove
 -- @treturn boolean index If the operation is successful
@@ -63,43 +41,6 @@ local flex = {}
 -- @name remove_widgets
 -- @class function
 
---- Fit the fixed layout into the given space
--- @param layout The layout you are modifying.
--- @param context The context in which we are fit.
--- @param orig_width The available width.
--- @param orig_height The available height.
--- @name fit
--- @class function
-
---- Reset a fixed layout. This removes all widgets from the layout.
--- @param layout The layout you are modifying.
--- @name reset
--- @class function
-
---- Replace the first instance of `widget` in the layout with `widget2`
--- @param widget The widget to replace
--- @param widget2 The widget to replace `widget` with
--- @tparam[opt=false] boolean recursive Digg in all compatible layouts to find the widget.
--- @treturn boolean If the operation is successful
--- @name replace_widget
--- @class function
-
---- Swap 2 widgets in a layout
--- @tparam number index1 The first widget index
--- @tparam number index2 The second widget index
--- @treturn boolean If the operation is successful
--- @name swap
--- @class function
-
---- Swap 2 widgets in a layout
--- If widget1 is present multiple time, only the first instance is swapped
--- @param widget1 The first widget
--- @param widget2 The second widget
--- @tparam[opt=false] boolean recursive Digg in all compatible layouts to find the widget.
--- @treturn boolean If the operation is successful
--- @name swap_widgets
--- @class function
-
 --- Insert a new widget in the layout at position `index`
 -- @tparam number index The position
 -- @param widget The widget
@@ -147,7 +88,7 @@ function flex:layout(_, width, height)
     return result
 end
 
---- Fit the flex layout into the given space.
+-- Fit the flex layout into the given space.
 -- @param context The context in which we are fit.
 -- @param orig_width The available width.
 -- @param orig_height The available height.
@@ -206,6 +147,7 @@ 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).
 -- @tparam widget ... Widgets that should be added to the layout.
+-- @function wibox.layout.flex.horizontal
 function flex.horizontal(...)
     return get_layout("horizontal", ...)
 end
@@ -213,6 +155,7 @@ 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).
 -- @tparam widget ... Widgets that should be added to the layout.
+-- @function wibox.layout.flex.vertical
 function flex.vertical(...)
     return get_layout("vertical", ...)
 end

lib/wibox/layout/ratio.lua

@@ -17,55 +17,7 @@ local util  = require("awful.util")
 
 local ratio = {}
 
---- Set a widget at a specific index, replace the current one
--- @tparam number index A widget or a widget index
--- @param widget2 The widget to take the place of the first one
--- @treturn boolean If the operation is successful
--- @name set
--- @class function
-
---- Replace the first instance of `widget` in the layout with `widget2`
--- @param widget The widget to replace
--- @param widget2 The widget to replace `widget` with
--- @tparam[opt=false] boolean recursive Digg in all compatible layouts to find the widget.
--- @treturn boolean If the operation is successful
--- @name replace_widget
--- @class function
-
---- Swap 2 widgets in a layout
--- @tparam number index1 The first widget index
--- @tparam number index2 The second widget index
--- @treturn boolean If the operation is successful
--- @name swap
--- @class function
-
---- Swap 2 widgets in a layout
--- If widget1 is present multiple time, only the first instance is swapped
--- @param widget1 The first widget
--- @param widget2 The second widget
--- @tparam[opt=false] boolean recursive Digg in all compatible layouts to find the widget.
--- @treturn boolean If the operation is successful
--- @name swap_widgets
--- @class function
-
---- Get all children of this layout.
--- @param layout The layout you are modifying.
--- @return a list of all widgets
--- @name get_children
--- @class function
-
---- Fit the ratio layout into the given space
--- @param layout The layout you are modifying.
--- @param context The context in which we are fit.
--- @tparam number orig_width The available width.
--- @tparam number orig_height The available height.
--- @name fit
--- @class function
-
---- Reset a ratio layout. This removes all widgets from the layout.
--- @param layout The layout you are modifying.
--- @name reset
--- @class function
+--@DOC_fixed_COMMON@
 
 -- Compute the sum of all ratio (ideally, it should be 1)
 local function gen_sum(self, i_s, i_e)

lib/wibox/layout/stack.lua

@@ -22,11 +22,7 @@ local util  = require("awful.util")
 
 local stack = {mt={}}
 
---- Get all direct children widgets
--- @param layout The layout you are modifying.
--- @return a list of all widgets
--- @name get_children
--- @class function
+--@DOC_fixed_COMMON@
 
 --- Add some widgets to the given stack layout
 -- @param layout The layout you are modifying.
@@ -34,48 +30,12 @@ local stack = {mt={}}
 -- @name add
 -- @class function
 
---- Set a widget at a specific index, replace the current one
--- @tparam number index A widget or a widget index
--- @param widget2 The widget to take the place of the first one
--- @treturn boolean If the operation is successful
--- @name set
--- @class function
-
 --- Remove a widget from the layout
 -- @tparam index The widget index to remove
 -- @treturn boolean index If the operation is successful
 -- @name remove
 -- @class function
 
---- Reset a stack layout. This removes all widgets from the layout.
--- @param layout The layout you are modifying.
--- @name reset
--- @class function
-
---- Replace the first instance of `widget` in the layout with `widget2`
--- @param widget The widget to replace
--- @param widget2 The widget to replace `widget` with
--- @tparam[opt=false] boolean recursive Digg in all compatible layouts to find the widget.
--- @treturn boolean If the operation is successful
--- @name replace_widget
--- @class function
-
---- Swap 2 widgets in a layout
--- @tparam number index1 The first widget index
--- @tparam number index2 The second widget index
--- @treturn boolean If the operation is successful
--- @name swap
--- @class function
-
---- Swap 2 widgets in a layout
--- If widget1 is present multiple time, only the first instance is swapped
--- @param widget1 The first widget
--- @param widget2 The second widget
--- @tparam[opt=false] boolean recursive Digg in all compatible layouts to find the widget.
--- @treturn boolean If the operation is successful
--- @name swap_widgets
--- @class function
-
 --- Insert a new widget in the layout at position `index`
 -- @tparam number index The position
 -- @param widget The widget
@@ -163,6 +123,10 @@ function stack:raise_widget(widget, recursive)
     end
 end
 
+--- Create a new stack layout.
+-- @function wibox.layout.stack
+-- @treturn widget A new stack layout
+
 local function new(...)
     local ret = fixed.horizontal(...)