From 276f5f8849b3846dce2cd0efebb0e0b96e1d223a Mon Sep 17 00:00:00 2001
From: Michael Gehring <mg@ebfe.org>
Date: Wed, 11 Jun 2008 02:46:30 +0200
Subject: [PATCH] [doxygen] Add \lvalue and convert existing doc.

Signed-off-by: Julien Danjou <julien@danjou.info>
---
 awesome.doxygen.in     |  1 +
 build-utils/gendoc.lua |  2 +-
 client.c               | 40 +++++++++++++++++++++++++++++++++++++++-
 keybinding.c           |  4 ++--
 mouse.c                |  5 ++---
 statusbar.c            | 19 ++++++++++++-------
 tag.c                  | 30 +++++++++++++++---------------
 titlebar.c             |  6 +++---
 widget.c               | 20 ++++++++++++--------
 9 files changed, 87 insertions(+), 40 deletions(-)

diff --git a/awesome.doxygen.in b/awesome.doxygen.in
index 64911d45..120ecc50 100644
--- a/awesome.doxygen.in
+++ b/awesome.doxygen.in
@@ -39,6 +39,7 @@ DISTRIBUTE_GROUP_DOC   = NO
 SUBGROUPING            = YES
 
 ALIASES += luastack="\par Lua Stack:"
+ALIASES += lvalue="- \em value "
 ALIASES += lparam="- \em param "
 ALIASES += lreturn="- \em returns "
 
diff --git a/build-utils/gendoc.lua b/build-utils/gendoc.lua
index e53928f6..52f5ba83 100755
--- a/build-utils/gendoc.lua
+++ b/build-utils/gendoc.lua
@@ -37,7 +37,7 @@ for i, line in ipairs(ilines) do
         end
         comment = nil
     elseif comment_start then
-		if not line:find("\\param") and not line:find("\\return") then
+		if not line:find("\\param") and not line:find("\\return") and not line:find("\\lvalue") then
 	        comment = comment .. line
 		end
     end
diff --git a/client.c b/client.c
index 7d4f2b9a..3b0d0d06 100644
--- a/client.c
+++ b/client.c
@@ -948,6 +948,7 @@ client_setborder(client_t *c, uint32_t width)
 /** Set the client border width and color.
  * \param L The Lua VM state.
  * \luastack
+ * \lvalue A client.
  * \lparam A table with `width' key for the border width in pixel and `color' key
  * for the border color.
  */
@@ -972,6 +973,7 @@ luaA_client_border_set(lua_State *L)
 /** Move the client to another screen.
  * \param L The Lua VM state.
  * \luastack
+ * \lvalue A client.
  * \lparam A screen number.
  */
 static int
@@ -987,6 +989,7 @@ luaA_client_screen_set(lua_State *L)
 /** Get the screen number the client is onto.
  * \param L The Lua VM state.
  * \luastack
+ * \lvalue A client.
  * \lreturn A screen number.
  */
 static int
@@ -1000,6 +1003,7 @@ luaA_client_screen_get(lua_State *L)
 /** Tag a client with a specified tag.
  * \param L The Lua VM state.
  * \luastack
+ * \lvalue A client.
  * \lparam A tag object.
  * \lparam A boolean value: true to add this tag to clients, false to remove.
  */
@@ -1024,6 +1028,7 @@ luaA_client_tag(lua_State *L)
 /** Check if a client is tagged with the specified tag.
  * \param L The Lua VM state.
  * \luastack
+ * \lvalue A client.
  * \lparam A tag object.
  * \lreturn A boolean value, true if the client is tagged with this tag, false
  * otherwise.
@@ -1040,6 +1045,7 @@ luaA_client_istagged(lua_State *L)
 /** Get the client coordinates on the display.
  * \param L The Lua VM state.
  * \luastack
+ * \lvalue A client.
  * \lreturn A table with keys `width', `height', `x' and `y'.
  */
 static int
@@ -1061,6 +1067,7 @@ luaA_client_coords_get(lua_State *L)
 /** Set client coordinates. This only operates if the client is floating.
  * \param L The Lua VM state.
  * \luastack
+ * \lvalue A client.
  * \lparam A table with keys: x, y, width, height.
  */
 static int
@@ -1086,6 +1093,7 @@ luaA_client_coords_set(lua_State *L)
  * Note: this requires an external composite manager.
  * \param L The Lua VM state.
  * \luastack
+ * \lvalue A client.
  * \lparam A floating value between 0 and 1.
  */
 static int
@@ -1101,6 +1109,9 @@ luaA_client_opacity_set(lua_State *L)
 
 /** Kill a client.
  * \param L The Lua VM state.
+ *
+ * \luastack
+ * \lvalue A client.
  */
 static int
 luaA_client_kill(lua_State *L)
@@ -1113,6 +1124,7 @@ luaA_client_kill(lua_State *L)
 /** Swap a client with another one.
  * \param L The Lua VM state.
  * \luastack
+ * \lvalue A client.
  * \lparam A client to swap with.
  */
 static int
@@ -1130,6 +1142,9 @@ luaA_client_swap(lua_State *L)
 
 /** Focus a client.
  * \param L The Lua VM state.
+ *
+ * \luastack
+ * \lvalue A client.
  */
 static int
 luaA_client_focus_set(lua_State *L)
@@ -1141,6 +1156,9 @@ luaA_client_focus_set(lua_State *L)
 
 /** Raise a client on top of others which are on the same layer.
  * \param L The Lua VM state.
+ *
+ * \luastack
+ * \lvalue A client.
  */
 static int
 luaA_client_raise(lua_State *L)
@@ -1153,6 +1171,7 @@ luaA_client_raise(lua_State *L)
 /** Set the client floating attribute.
  * \param L The Lua VM state.
  * \luastack
+ * \lparam A client.
  * \lparam A boolean, true to set, false to unset.
  */
 static int
@@ -1167,6 +1186,7 @@ luaA_client_floating_set(lua_State *L)
 /** Check if a client has the floating attribute.
  * \param L The Lua VM state.
  * \luastack
+ * \lvalue A client.
  * \lreturn A boolean, true if the client has the floating attribute set, false
  * otherwise.
  */
@@ -1192,6 +1212,9 @@ luaA_client_eq(lua_State *L)
 
 /** Redraw a client by unmapping and mapping it quickly.
  * \param L The Lua VM state.
+ *
+ * \luastack
+ * \lvalue A client.
  */
 static int
 luaA_client_redraw(lua_State *L)
@@ -1205,6 +1228,7 @@ luaA_client_redraw(lua_State *L)
 /** Return a formated string for a client.
  * \param L The Lua VM state.
  * \luastack
+ * \lvalue  A client.
  * \lreturn A string.
  */
 static int
@@ -1218,6 +1242,7 @@ luaA_client_tostring(lua_State *L)
 /** Get the client name.
  * \param L The Lua VM state.
  * \luastack
+ * \lvalue A client.
  * \lreturn A string with the client class.
  */
 static int
@@ -1235,6 +1260,7 @@ luaA_client_class_get(lua_State *L)
 /** Set the default icon for this client.
  * \param L The Lua VM state.
  * \luastack
+ * \lvalue A client.
  * \lparam A path to an icon image, or nil to remove.
  */
 static int
@@ -1252,6 +1278,7 @@ luaA_client_icon_set(lua_State *L)
 /** Get the client name.
  * \param L The Lua VM state.
  * \luastack
+ * \lvalue A client.
  * \lreturn A string with the client name.
  */
 static int
@@ -1265,6 +1292,7 @@ luaA_client_name_get(lua_State *L)
 /** Change the client name. It'll change it only from awesome point of view.
  * \param L The Lua VM state.
  * \luastack
+ * \lvalue A client.
  * \lparam A string with the new client name.
  */
 static int
@@ -1280,6 +1308,7 @@ luaA_client_name_set(lua_State *L)
 /** Set the client's titlebar.
  * \param L The Lua VM state.
  * \luastack
+ * \lvalue A client.
  * \lparam A titlebar.
  */
 static int
@@ -1323,6 +1352,7 @@ luaA_client_titlebar_set(lua_State *L)
 /** Get the titlebar of a client.
  * \param L The Lua VM state.
  * \luastack
+ * \lvalue A client.
  * \lreturn A titlebar or nil if the client has no titlebar.
  */
 static int
@@ -1338,6 +1368,8 @@ luaA_client_titlebar_get(lua_State *L)
 
 /** Stop managing a client.
  * \param L The Lua VM state.
+ * \luastack
+ * \lvalue A client.
  */
 static int
 luaA_client_unmanage(lua_State *L)
@@ -1349,6 +1381,9 @@ luaA_client_unmanage(lua_State *L)
 
 /** Hide a client.
  * \param L The Lua VM state.
+ *
+ * \luastack
+ * \lvalue A client.
  */
 static int
 luaA_client_hide(lua_State *L)
@@ -1361,6 +1396,9 @@ luaA_client_hide(lua_State *L)
 
 /** Unhide a client.
  * \param L The Lua VM state.
+ *
+ * \luastack
+ * \lvalue A client.
  */
 static int
 luaA_client_unhide(lua_State *L)
@@ -1375,7 +1413,7 @@ luaA_client_unhide(lua_State *L)
  * \param L The Lua VM state.
  *
  * \luastack
- *
+ * \lvalue A client.
  * \lreturn A boolean, true if the client has been hidden with hide(), false
  * otherwise.
  */
diff --git a/keybinding.c b/keybinding.c
index dec94e6f..b2d415f7 100644
--- a/keybinding.c
+++ b/keybinding.c
@@ -91,7 +91,7 @@ luaA_keybinding_new(lua_State *L)
  * \param L The Lua VM state.
  *
  * \luastack
- * \lparam A keybinding.
+ * \lvalue A keybinding.
  */
 static int
 luaA_keybinding_add(lua_State *L)
@@ -116,7 +116,7 @@ luaA_keybinding_add(lua_State *L)
  * \param L The Lua VM state.
  *
  * \luastack
- * \lparam A keybinding.
+ * \lvalue A keybinding.
  */
 static int
 luaA_keybinding_remove(lua_State *L)
diff --git a/mouse.c b/mouse.c
index a71e91c5..4b6d1bca 100644
--- a/mouse.c
+++ b/mouse.c
@@ -720,7 +720,6 @@ mouse_client_resize(client_t *c, corner_t corner)
  * \param L The Lua VM state.
  *
  * \luastack
- * \lparam A client.
  * \lparam The x coordinate.
  * \lparam The y coordinate.
  */
@@ -740,7 +739,7 @@ luaA_mouse_coords_set(lua_State *L)
  * \param L The Lua VM state.
  *
  * \luastack
- * \lparam A client.
+ * \lvalue A client.
  * \lparam An optionnal corner, such as bottomleft, topright, etc.
  */
 int
@@ -760,7 +759,7 @@ luaA_client_mouse_resize(lua_State *L)
  * \param L The Lua VM state.
  *
  * \luastack
- * \lparam A client.
+ * \lvalue A client.
  * \lparam The pixel to snap.
  */
 int
diff --git a/statusbar.c b/statusbar.c
index 660ce81c..2e3012f3 100644
--- a/statusbar.c
+++ b/statusbar.c
@@ -277,7 +277,7 @@ statusbar_position_update(statusbar_t *statusbar, position_t position)
  * \param L The Lua VM state.
  *
  * \luastack
- * \lparam A statusbar.
+ * \lvalue A statusbar.
  * \lparam Another statusbar.
  * \return True if statusbar are equals, false otherwise.
  */
@@ -294,7 +294,7 @@ luaA_statusbar_eq(lua_State *L)
  * \param L The Lua VM state.
  *
  * \luastack
- * \lparam A statusbar.
+ * \lvalue A statusbar.
  * \lparam A position: left, right, top, bottom or off.
  */
 static int
@@ -318,7 +318,7 @@ luaA_statusbar_position_set(lua_State *L)
  * \param L The Lua VM state.
  *
  * \luastack
- * \lparam A statusbar.
+ * \lvalue A statusbar.
  * \lreturn The statusbar position.
  */
 static int
@@ -333,7 +333,7 @@ luaA_statusbar_position_get(lua_State *L)
  * \param L The Lua VM state.
  *
  * \luastack
- * \lparam A statusbar,
+ * \lvalue A statusbar,
  * \lparam An alignment: right, left or center.
  */
 static int
@@ -353,7 +353,7 @@ luaA_statusbar_align_set(lua_State *L)
  * \param L The Lua VM state.
  *
  * \luastack
- * \lparam A statusbar.
+ * \lvalue A statusbar.
  */
 static int
 luaA_statusbar_tostring(lua_State *L)
@@ -367,7 +367,7 @@ luaA_statusbar_tostring(lua_State *L)
  * \param L The Lua VM state.
  *
  * \luastack
- * \lparam A statusbar.
+ * \lvalue A statusbar.
  * \lparam A widget.
  */
 static int
@@ -389,7 +389,7 @@ luaA_statusbar_widget_add(lua_State *L)
  * \param L The Lua VM state.
  *
  * \luastack
- * \lparam A stausbar
+ * \lvalue A stausbar
  * \lparam A screen number.
  */
 static int
@@ -426,6 +426,10 @@ luaA_statusbar_add(lua_State *L)
 }
 
 /** Remove the statusbar its screen.
+ * \param L The Lua VM state.
+ *
+ * \luastack
+ * \lvalue A statusbar
  */
 static int
 luaA_statusbar_remove(lua_State *L)
@@ -514,6 +518,7 @@ luaA_statusbar_userdata_new(statusbar_t *t)
  * \param L The Lua VM state.
  *
  * \luastack
+ * \lvalue A statusbar.
  * \lreturn A table with all widgets from the statusbar.
  */
 static int
diff --git a/tag.c b/tag.c
index 8d9544d0..b5c7c168 100644
--- a/tag.c
+++ b/tag.c
@@ -239,7 +239,7 @@ tag_view_only_byindex(int screen, int dindex)
  * \param L The Lua VM state.
  *
  * \luastack
- * \lparam A tag.
+ * \lvalue A tag.
  * \lparam Another tag.
  * \lreturn True if tags are equals.
  */
@@ -256,7 +256,7 @@ luaA_tag_eq(lua_State *L)
  * \param L The Lua VM state.
  *
  * \luastack
- * \lparam A tag.
+ * \lvalue A tag.
  * \lreturn A string.
  */
 static int
@@ -271,7 +271,7 @@ luaA_tag_tostring(lua_State *L)
  * \param L The Lua VM state.
  *
  * \luastack
- * \lparam A tag.
+ * \lvalue A tag.
  * \lparam A screen number.
  */
 static int
@@ -356,7 +356,7 @@ luaA_tag_new(lua_State *L)
  * \param L The Lua VM state.
  *
  * \luastack
- * \lparam A tag.
+ * \lvalue A tag.
  * \lparam A boolean value, true to view tag, false otherwise.
  */
 static int
@@ -372,7 +372,7 @@ luaA_tag_view(lua_State *L)
  * \param L The Lua VM state.
  *
  * \luastack
- * \lparam A tag.
+ * \lvalue A tag.
  * \lreturn True if the tag is viewed, false otherwise.
  */
 static int
@@ -388,7 +388,7 @@ luaA_tag_isselected(lua_State *L)
  * \param L The Lua VM state.
  *
  * \luastack
- * \lparam A tag.
+ * \lvalue A tag.
  * \lparam The master width ratio value, between 0 and 1.
  */
 static int
@@ -412,7 +412,7 @@ luaA_tag_mwfact_set(lua_State *L)
  * \param L The Lua VM state.
  *
  * \luastack
- * \lparam A tag.
+ * \lvalue A tag.
  * \lreturn The master width ratio value.
  */
 static int
@@ -428,7 +428,7 @@ luaA_tag_mwfact_get(lua_State *L)
  * \param L The Lua VM state.
  *
  * \luastack
- * \lparam A tag.
+ * \lvalue A tag.
  * \lparam The number of columns, at least 1.
  */
 static int
@@ -452,7 +452,7 @@ luaA_tag_ncol_set(lua_State *L)
  * \param L The Lua VM state.
  *
  * \luastack
- * \lparam A tag.
+ * \lvalue A tag.
  * \lreturn The number of column.
  */
 static int
@@ -468,7 +468,7 @@ luaA_tag_ncol_get(lua_State *L)
  * \param L The Lua VM state.
  *
  * \luastack
- * \lparam A tag.
+ * \lvalue A tag.
  * \lparam The number of master windows.
  */
 static int
@@ -492,7 +492,7 @@ luaA_tag_nmaster_set(lua_State *L)
  * \param L The Lua VM state.
  *
  * \luastack
- * \lparam A tag.
+ * \lvalue A tag.
  * \lreturn The number of master windows.
  */
 static int
@@ -507,7 +507,7 @@ luaA_tag_nmaster_get(lua_State *L)
  * \param L The Lua VM state.
  *
  * \luastack
- * \lparam A tag.
+ * \lvalue A tag.
  * \lreturn The tag name.
  */
 static int
@@ -522,7 +522,7 @@ luaA_tag_name_get(lua_State *L)
  * \param L The Lua VM state.
  *
  * \luastack
- * \lparam A tag.
+ * \lvalue A tag.
  * \lparam A string with the new tag name.
  */
 static int
@@ -550,7 +550,7 @@ luaA_tag_gc(lua_State *L)
  * \param L The Lua VM state.
  *
  * \luastack
- * \lparam A tag.
+ * \lvalue A tag.
  * \lreturn The layout name.
  */
 static int
@@ -566,7 +566,7 @@ luaA_tag_layout_get(lua_State *L)
  * \param L The Lua VM state.
  *
  * \luastack
- * \lparam A tag.
+ * \lvalue A tag.
  * \lparam A layout name.
  */
 static int
diff --git a/titlebar.c b/titlebar.c
index 3e8ee567..da0f5739 100644
--- a/titlebar.c
+++ b/titlebar.c
@@ -442,7 +442,7 @@ luaA_titlebar_new(lua_State *L)
  * \param L The Lua VM state.
  *
  * \luastack
- * \lparam A titlebar.
+ * \lvalue A titlebar.
  * \lparam A widget.
  */
 static int
@@ -471,7 +471,7 @@ luaA_titlebar_widget_add(lua_State *L)
  * \param L The Lua VM state.
  *
  * \luastack
- * \lparam A titlebar
+ * \lvalue A titlebar
  * \lreturn A table with all widgets from the titlebar.
  */
 static int
@@ -499,7 +499,7 @@ luaA_titlebar_widget_get(lua_State *L)
  * \param L The Lua VM state.
  *
  * \luastack
- * \lparam A titlebar.
+ * \lvalue A titlebar.
  * \lreturn A client if the titlebar is attached, nil otherwise.
  */
 static int
diff --git a/widget.c b/widget.c
index 9be6c8c0..1ecb290c 100644
--- a/widget.c
+++ b/widget.c
@@ -349,7 +349,7 @@ luaA_widget_new(lua_State *L)
  * \param L The Lua VM state.
  *
  * \luastack
- * \lparam A widget.
+ * \lvalue A widget.
  * \lparam A table containing modifiers keys.
  * \lparam A button number.
  * \lparam A function to execute. Some widgets may pass arguments to this
@@ -429,7 +429,7 @@ widget_tell_managestatus(widget_t *widget, widget_tell_status_t status, const ch
  * \param L The Lua VM state.
  *
  * \luastack
- * \lparam A widget.
+ * \lvalue A widget.
  * \lparam The property name.
  * \lparam The property value.
  */
@@ -452,7 +452,7 @@ luaA_widget_set(lua_State *L)
  * \param L The Lua VM state.
  *
  * \luastack
- * \lparam A widget.
+ * \lvalue A widget.
  */
 static int
 luaA_widget_gc(lua_State *L)
@@ -467,7 +467,7 @@ luaA_widget_gc(lua_State *L)
  * \param L The Lua VM state.
  *
  * \luastack
- * \lparam A widget.
+ * \lvalue A widget.
  */
 static int
 luaA_widget_tostring(lua_State *L)
@@ -481,7 +481,7 @@ luaA_widget_tostring(lua_State *L)
  * \param L The Lua VM state.
  *
  * \luastack
- * \lparam A widget.
+ * \lvalue A widget.
  * \lparam Another widget.
  * \lreturn True if widgets are equal.
  */
@@ -498,7 +498,7 @@ luaA_widget_eq(lua_State *L)
  * \param L The Lua VM state.
  *
  * \luastack
- * \lparam A widget.
+ * \lvalue A widget.
  * \lparam A string with the new widget name.
  */
 static int
@@ -515,7 +515,7 @@ luaA_widget_name_set(lua_State *L)
  * \param L The Lua VM state.
  *
  * \luastack
- * \lparam A widget.
+ * \lvalue A widget.
  * \lreturn A string with the name of the widget.
  */
 static int
@@ -531,7 +531,7 @@ luaA_widget_name_get(lua_State *L)
  * \param L The Lua VM state.
  *
  * \luastack
- * \lparam A widget.
+ * \lvalue A widget.
  * \lparam A boolean value.
  */
 static int
@@ -544,6 +544,10 @@ luaA_widget_visible_set(lua_State *L)
 }
 
 /** Get the visible attribute of a widget.
+ * \param L The Lua VM state.
+ *
+ * \luastack
+ * \lvalue A widget.
  * \return A boolean value, true if the widget is visible, false otherwise.
  */
 static int