diff --git a/lib/awful/menu.lua.in b/lib/awful/menu.lua.in
index 8cd6c519..4b11d8c9 100644
--- a/lib/awful/menu.lua.in
+++ b/lib/awful/menu.lua.in
@@ -386,6 +386,32 @@ end
 -- </ul>
 -- @param parent Specify the parent menu if we want to open a submenu, this value should never be set by the user.
 -- @param num Specify the parent's clicked item number if we want to open a submenu, this value should never be set by the user.
+-- @usage The following function builds, and shows a menu of clients that match
+-- a particular rule. Bound to a key, it can for example be used to select from
+-- dozens of terminals open on several tags. With the use of
+-- <code>match_any</code> instead of <code>match</code>, menu of clients with
+-- different classes can also be build.
+--
+-- <p><code>
+--                     function terminal_menu ()                           <br/>
+-- &nbsp;                terms = {}                                        <br/>
+-- &nbsp;                for i, c in pairs(client.get()) do                <br/>
+-- &nbsp;&nbsp;            if awful.rules.match(c, {class = "URxvt"}) then <br/>
+-- &nbsp;&nbsp;&nbsp;        terms[i] =                                    <br/>
+-- &nbsp;&nbsp;&nbsp;          {c.name,                                    <br/>
+-- &nbsp;&nbsp;&nbsp;           function()                                 <br/>
+-- &nbsp;&nbsp;&nbsp;&nbsp;       awful.tag.viewonly(c:tags()[1])          <br/>
+-- &nbsp;&nbsp;&nbsp;&nbsp;       client.focus = c                         <br/>
+-- &nbsp;&nbsp;&nbsp;           end,                                       <br/>
+-- &nbsp;&nbsp;&nbsp;           c.icon                                     <br/>
+-- &nbsp;&nbsp;&nbsp;          }                                           <br/>
+-- &nbsp;&nbsp;            end                                             <br/>
+-- &nbsp;                end                                               <br/>
+-- &nbsp;                m = awful.menu({items = terms})                   <br/>
+-- &nbsp;                m:show({keygrabber=true})                         <br/>
+-- &nbsp;                return m                                          <br/>
+--                     end                                                 <br/>
+--</code></p>
 function new(menu, parent, num)
     -- Create a table to store our menu informations
     local data = {}