From 404ec8eb24e907cd378ccb6ceee9b62b16b46bb1 Mon Sep 17 00:00:00 2001
From: Brian Gianforcaro <b.gianfo@gmail.com>
Date: Mon, 27 Jul 2009 00:20:00 -0400
Subject: [PATCH] Fix doxygen generation warnings.

Signed-off-by: Brian Gianforcaro <b.gianfo@gmail.com>
Signed-off-by: Julien Danjou <julien@danjou.info>
---
 awesome.c          |  6 ++++--
 awesome.doxygen.in |  1 -
 client.c           |  3 ++-
 draw.c             |  2 +-
 ewmh.c             |  1 +
 image.c            | 10 +++++-----
 key.c              |  2 +-
 luaa.c             |  2 +-
 mouse.c            |  2 +-
 mousegrabber.c     |  4 +++-
 property.c         | 17 ++++++++++++++---
 screen.c           |  1 -
 spawn.c            |  1 -
 swindow.c          |  7 ++++++-
 swindow.h          |  1 +
 systray.c          |  3 +++
 tag.c              |  2 +-
 titlebar.c         |  1 -
 wibox.c            |  2 +-
 window.c           |  4 ++--
 20 files changed, 47 insertions(+), 25 deletions(-)

diff --git a/awesome.c b/awesome.c
index 785f473c3..88ab3c4ed 100644
--- a/awesome.c
+++ b/awesome.c
@@ -254,7 +254,8 @@ signal_fatal(int signum)
 }
 
 /** Function to exit on some signals.
- * \param sig the signal received, unused
+ * \param w the signal received, unused
+ * \param revents currently unused
  */
 static void
 exit_on_signal(EV_P_ ev_signal *w, int revents)
@@ -270,7 +271,8 @@ awesome_restart(void)
 }
 
 /** Function to restart aweome on some signals.
- * \param sig the signam received, unused
+ * \param w the signam received, unused
+ * \param revents Currently unused
  */
 static void
 restart_on_signal(EV_P_ ev_signal *w, int revents)
diff --git a/awesome.doxygen.in b/awesome.doxygen.in
index 4df2775c8..07c03e58d 100644
--- a/awesome.doxygen.in
+++ b/awesome.doxygen.in
@@ -26,7 +26,6 @@ SHORT_NAMES            = NO
 JAVADOC_AUTOBRIEF      = NO
 QT_AUTOBRIEF           = NO
 MULTILINE_CPP_IS_BRIEF = NO
-DETAILS_AT_TOP         = NO
 INHERIT_DOCS           = YES
 SEPARATE_MEMBER_PAGES  = NO
 TAB_SIZE               = 4
diff --git a/client.c b/client.c
index ae63f9072..a103a55a9 100644
--- a/client.c
+++ b/client.c
@@ -203,6 +203,7 @@ client_unfocus(client_t *c)
 
 /** Check if client supports protocol a protocole in WM_PROTOCOL.
  * \param c The client.
+ * \param atom The protocol atom to check for.
  * \return True if client has the atom in protocol, false otherwise.
  */
 bool
@@ -321,7 +322,7 @@ client_focus(client_t *c)
 /** Stack a window below.
  * \param c The client.
  * \param previous The previous window on the stack.
- * \param return The next-previous!
+ * \return The next-previous!
  */
 static xcb_window_t
 client_stack_above(client_t *c, xcb_window_t previous)
diff --git a/draw.c b/draw.c
index a1e722ff9..ddc2d6c82 100644
--- a/draw.c
+++ b/draw.c
@@ -197,7 +197,7 @@ draw_context_init(draw_context_t *d, int phys_screen,
 /** Draw text into a draw context.
  * \param ctx Draw context  to draw to.
  * \param data Draw text context data.
- * \param elip Ellipsize mode.
+ * \param ellip Ellipsize mode.
  * \param wrap Wrap mode.
  * \param align Text alignment.
  * \param margin Margin to respect when drawing text.
diff --git a/ewmh.c b/ewmh.c
index 2fb48a442..1a72953d0 100644
--- a/ewmh.c
+++ b/ewmh.c
@@ -577,6 +577,7 @@ ewmh_client_check_hints(client_t *c)
 
 /** Process the WM strut of a client.
  * \param c The client.
+ * \param strut_r (Optional) An existing reply.
  */
 void
 ewmh_process_client_strut(client_t *c, xcb_get_property_reply_t *strut_r)
diff --git a/image.c b/image.c
index a71df33ea..5ccd50956 100644
--- a/image.c
+++ b/image.c
@@ -347,7 +347,7 @@ luaA_image_crop_and_scale(lua_State *L)
 /** Draw a pixel in an image
  * \param L The Lua VM state
  * \luastack
- * \lvalua An image.
+ * \lvalue An image.
  * \lparam The x coordinate of the pixel to draw
  * \lparam The y coordinate of the pixel to draw
  * \lparam The color to draw the pixel in
@@ -379,7 +379,7 @@ luaA_image_draw_pixel(lua_State *L)
 /** Draw a line in an image
  * \param L The Lua VM state
  * \luastack
- * \lvalua An image.
+ * \lvalue An image.
  * \lparam The x1 coordinate of the line to draw
  * \lparam The y1 coordinate of the line to draw
  * \lparam The x2 coordinate of the line to draw
@@ -415,7 +415,7 @@ luaA_image_draw_line(lua_State *L)
 /** Draw a rectangle in an image
  * \param L The Lua VM state
  * \luastack
- * \lvalua An image.
+ * \lvalue An image.
  * \lparam The x coordinate of the rectangles top left corner
  * \lparam The y coordinate of the rectangles top left corner
  * \lparam The width of the rectangle
@@ -509,7 +509,7 @@ luaA_table_to_color_range(lua_State *L, int ud)
  * \param L The Lua VM state.
  * \return The number of elements pushed on stack.
  * \luastack
- * \lvalua An image.
+ * \lvalue An image.
  * \lparam The x coordinate of the rectangles top left corner.
  * \lparam The y coordinate of the rectangles top left corner.
  * \lparam The width of the rectangle.
@@ -550,7 +550,7 @@ luaA_image_draw_rectangle_gradient(lua_State *L)
 /** Draw a circle in an image
  * \param L The Lua VM state
  * \luastack
- * \lvalua An image.
+ * \lvalue An image.
  * \lparam The x coordinate of the center of the circle
  * \lparam The y coordinate of the center of the circle
  * \lparam The horizontal amplitude (width)
diff --git a/key.c b/key.c
index f30d33279..36e7e1d6a 100644
--- a/key.c
+++ b/key.c
@@ -1087,7 +1087,7 @@ luaA_key_array_get(lua_State *L, key_array_t *keys)
 
 /** Push a modifier set to a Lua table.
  * \param L The Lua VM state.
- * \param mod The modifier.
+ * \param modifiers The modifier.
  * \return The number of elements pushed on stack.
  */
 int
diff --git a/luaa.c b/luaa.c
index 992c6ae50..ba5f7d143 100644
--- a/luaa.c
+++ b/luaa.c
@@ -139,7 +139,7 @@ luaA_mbstrlen(lua_State *L)
 
 /** Overload standard Lua next function to use __next key on metatable.
  * \param L The Lua VM state.
- * \param The number of elements pushed on stack.
+ * \return The number of elements pushed on stack.
  */
 static int
 luaAe_next(lua_State *L)
diff --git a/mouse.c b/mouse.c
index f6b185fe3..59b8a91cc 100644
--- a/mouse.c
+++ b/mouse.c
@@ -60,7 +60,7 @@ mouse_query_pointer(xcb_window_t window, int16_t *x, int16_t *y, xcb_window_t *c
 }
 
 /** Get the pointer position on the screen.
- * \param screen This will be set to the screen the mouse is on.
+ * \param s This will be set to the screen the mouse is on.
  * \param x This will be set to the Pointer-x-coordinate relative to window.
  * \param y This will be set to the Pointer-y-coordinate relative to window.
  * \param child This will be set to the window under the pointer.
diff --git a/mousegrabber.c b/mousegrabber.c
index 3544feaf6..8d12f9b75 100644
--- a/mousegrabber.c
+++ b/mousegrabber.c
@@ -72,7 +72,9 @@ mousegrabber_grab(xcb_cursor_t cursor)
 
 /** Handle mouse motion events.
  * \param L Lua stack to push the pointer motion.
- * \param ev Received mouse motion event.
+ * \param x The received mouse event x component.
+ * \param y The received mouse event y component.
+ * \param mask The received mouse event bit mask.
  */
 void
 mousegrabber_handleevent(lua_State *L, int x, int y, uint16_t mask)
diff --git a/property.c b/property.c
index e2cfa41cd..fc6a1d4cb 100644
--- a/property.c
+++ b/property.c
@@ -116,6 +116,7 @@ property_handle_wm_client_leader(void *data,
 
 /** Update the size hints of a client.
  * \param c The client.
+ * \param reply (Optional) An existing reply.
  */
 void
 property_update_wm_normal_hints(client_t *c, xcb_get_property_reply_t *reply)
@@ -153,6 +154,7 @@ property_handle_wm_normal_hints(void *data,
 
 /** Update the WM hints of a client.
  * \param c The client.
+ * \param reply (Optional) An existing reply.
  */
 void
 property_update_wm_hints(client_t *c, xcb_get_property_reply_t *reply)
@@ -203,7 +205,6 @@ property_handle_wm_hints(void *data,
 
 /** Update client name attribute with its new title.
  * \param c The client.
- * \param Return true if it has been updated.
  */
 void
 property_update_wm_name(client_t *c)
@@ -257,7 +258,6 @@ property_update_wm_class(client_t *c, xcb_get_property_reply_t *reply)
 
 /** Update client icon name attribute with its new title.
  * \param c The client.
- * \param Return true if it has been updated.
  */
 void
 property_update_wm_icon_name(client_t *c)
@@ -384,6 +384,14 @@ property_update_wm_protocols(client_t *c)
     }
 }
 
+/** The property notify event handler.
+ * \param data currently unused.
+ * \param connection currently unusued.
+ * \param state currently unused.
+ * \param window The window to obtain update protocols from.
+ * \param name currently unused.
+ * \param reply currently unused.
+ */
 static int
 property_handle_wm_protocols(void *data,
                              xcb_connection_t *connection,
@@ -403,7 +411,10 @@ property_handle_wm_protocols(void *data,
 /** The property notify event handler.
  * \param data currently unused.
  * \param connection The connection to the X server.
- * \param ev The event.
+ * \param state currently unused
+ * \param window The window to obtain update the property with.
+ * \param name The protocol atom, currently unused.
+ * \param reply (Optional) An existing reply.
  */
 static int
 property_handle_xembed_info(void *data __attribute__ ((unused)),
diff --git a/screen.c b/screen.c
index 08e542356..1f5e4f4ec 100644
--- a/screen.c
+++ b/screen.c
@@ -161,7 +161,6 @@ screen_getbycoord(screen_t *screen, int x, int y)
 
 /** Get screens info.
  * \param screen Screen.
- * \param wiboxes Wiboxes list to remove.
  * \param strut Honor windows strut.
  * \return The screen area.
  */
diff --git a/spawn.c b/spawn.c
index a0f1a7ed4..2998dec6f 100644
--- a/spawn.c
+++ b/spawn.c
@@ -48,7 +48,6 @@ DO_ARRAY(SnStartupSequence *, SnStartupSequence, a_sn_startup_sequence_unref)
 SnStartupSequence_array_t sn_waits;
 
 /** Remove a SnStartupSequence pointer from an array and forget about it.
- * \param array The startup sequence array.
  * \param s The startup sequence to found, remove and unref.
  * \return True if found and removed.
  */
diff --git a/swindow.c b/swindow.c
index 061d680a5..6357bd622 100644
--- a/swindow.c
+++ b/swindow.c
@@ -64,8 +64,9 @@ simplewindow_draw_context_update(simple_window_t *sw, xcb_screen_t *s)
  * \param phys_screen Physical screen number.
  * \param geometry Window geometry.
  * \param border_width Window border width.
+ * \param border_color Window border color.
  * \param orientation The rendering orientation.
- * \param bg Default foreground color.
+ * \param fg Default foreground color.
  * \param bg Default background color.
  */
 void
@@ -257,6 +258,10 @@ simplewindow_moveresize(simple_window_t *sw, area_t geom)
 
 /** Refresh the window content by copying its pixmap data to its window.
  * \param sw The simple window to refresh.
+ * \param x The copy starting point x component.
+ * \param y The copy starting point y component.
+ * \param w The copy width from the x component.
+ * \param h The copy height from the y component.
  */
 void
 simplewindow_refresh_pixmap_partial(simple_window_t *sw,
diff --git a/swindow.h b/swindow.h
index 316e5e268..fcf8d9ed3 100644
--- a/swindow.h
+++ b/swindow.h
@@ -82,6 +82,7 @@ simplewindow_refresh_pixmap(simple_window_t *sw)
 }
 
 /** Set a simplewindow's opacity.
+ * \param sw The window the adjust the opacity of.
  * \param opacity A value between 0 and 1 which describes the opacity.
  */
 static inline void
diff --git a/systray.c b/systray.c
index f4f804794..b28638215 100644
--- a/systray.c
+++ b/systray.c
@@ -126,6 +126,9 @@ systray_cleanup(int phys_screen)
 
 /** Handle a systray request.
  * \param embed_win The window to embed.
+ * \param phys_screen The physical monitor to display on.
+ * \param info The embeding info
+ * \return 0 on no error.
  */
 int
 systray_request_handle(xcb_window_t embed_win, int phys_screen, xembed_info_t *info)
diff --git a/tag.c b/tag.c
index 8400b5309..9a4bd2d94 100644
--- a/tag.c
+++ b/tag.c
@@ -75,7 +75,7 @@ tag_view(tag_t *tag, bool view)
 }
 
 /** Append a tag which on top of the stack to a screen.
- * \param screen the screen id
+ * \param s screen the screen id
  */
 void
 tag_append_to_screen(screen_t *s)
diff --git a/titlebar.c b/titlebar.c
index 1379d58cd..56ef7185f 100644
--- a/titlebar.c
+++ b/titlebar.c
@@ -217,7 +217,6 @@ titlebar_client_detach(client_t *c)
 
 /** Attach a wibox to a client as its titlebar.
  * \param c The client.
- * \param ud The index of the wibox on the stack.
  */
 void
 titlebar_client_attach(client_t *c)
diff --git a/wibox.c b/wibox.c
index 07043c2f5..ae2ae1a34 100644
--- a/wibox.c
+++ b/wibox.c
@@ -283,7 +283,7 @@ wibox_systray_refresh(wibox_t *wibox)
 }
 
 /** Get a wibox by its window.
- * \param w The window id.
+ * \param win The window id.
  * \return A wibox if found, NULL otherwise.
  */
 wibox_t *
diff --git a/window.c b/window.c
index dae553fb8..cad9c07d0 100644
--- a/window.c
+++ b/window.c
@@ -110,7 +110,7 @@ window_buttons_grab(xcb_window_t win, button_array_t *buttons)
 }
 
 /** Get the opacity of a window.
- * \param The window.
+ * \param win The window.
  * \return The opacity, between 0 and 1 or -1 or no opacity set.
  */
 double
@@ -131,7 +131,7 @@ window_opacity_get(xcb_window_t win)
 }
 
 /** Get the opacity of a window.
- * \param A reply to a get property request for _NET_WM_WINDOW_OPACITY.
+ * \param prop_r A reply to a get property request for _NET_WM_WINDOW_OPACITY.
  * \return The opacity, between 0 and 1.
  */
 double window_opacity_get_from_reply(xcb_get_property_reply_t *prop_r)