diff --git a/docs/images/mouse.svg b/docs/images/mouse.svg
new file mode 100644
index 000000000..e56eff51c
--- /dev/null
+++ b/docs/images/mouse.svg
@@ -0,0 +1,253 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!-- Created with Inkscape (http://www.inkscape.org/) -->
+
+<svg
+   xmlns:dc="http://purl.org/dc/elements/1.1/"
+   xmlns:cc="http://creativecommons.org/ns#"
+   xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
+   xmlns:svg="http://www.w3.org/2000/svg"
+   xmlns="http://www.w3.org/2000/svg"
+   xmlns:sodipodi="http://sodipodi.sourceforge.net/DTD/sodipodi-0.dtd"
+   xmlns:inkscape="http://www.inkscape.org/namespaces/inkscape"
+   width="154.33519mm"
+   height="83.532181mm"
+   viewBox="0 0 546.85725 295.98017"
+   id="svg2"
+   version="1.1"
+   inkscape:version="0.91 r13725"
+   sodipodi:docname="mouse.svg">
+  <defs
+     id="defs4" />
+  <sodipodi:namedview
+     id="base"
+     pagecolor="#ffffff"
+     bordercolor="#666666"
+     borderopacity="1.0"
+     inkscape:pageopacity="0.0"
+     inkscape:pageshadow="2"
+     inkscape:zoom="1.4"
+     inkscape:cx="360.06759"
+     inkscape:cy="366.74179"
+     inkscape:document-units="pt"
+     inkscape:current-layer="g5476"
+     showgrid="false"
+     showguides="false"
+     inkscape:guide-bbox="true"
+     inkscape:window-width="1916"
+     inkscape:window-height="1021"
+     inkscape:window-x="0"
+     inkscape:window-y="16"
+     inkscape:window-maximized="1"
+     fit-margin-top="0"
+     fit-margin-left="0"
+     fit-margin-right="0"
+     fit-margin-bottom="0" />
+  <metadata
+     id="metadata7">
+    <rdf:RDF>
+      <cc:Work
+         rdf:about="">
+        <dc:format>image/svg+xml</dc:format>
+        <dc:type
+           rdf:resource="http://purl.org/dc/dcmitype/StillImage" />
+        <dc:title></dc:title>
+      </cc:Work>
+    </rdf:RDF>
+  </metadata>
+  <g
+     inkscape:label="Layer 1"
+     inkscape:groupmode="layer"
+     id="layer1"
+     transform="translate(738.15802,-608.17116)">
+    <g
+       id="g5476"
+       transform="translate(173.74631,0)">
+      <path
+         sodipodi:nodetypes="cccccccccc"
+         inkscape:connector-curvature="0"
+         id="path4136"
+         d="m -728.15879,608.42602 178.5142,0 c 9.38939,0.26627 10.95278,7.73823 10.83892,14.69669 l 0,230.46648 c 0.30959,23.52499 -24.37716,50.18749 -47.93254,50.01303 l -104.98806,0.29423 c -20.09841,0.0248 -45.84989,-25.43284 -46.17689,-51.01859 l 0.0204,-227.59279 c 0.18644,-8.43842 1.99483,-16.50279 9.72396,-16.85905 z"
+         style="fill:none;fill-rule:evenodd;stroke:#000000;stroke-width:0.50971645;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1" />
+      <path
+         sodipodi:nodetypes="cc"
+         inkscape:connector-curvature="0"
+         id="path4138"
+         d="m -733.20425,673.55031 189.76854,0"
+         style="fill:none;fill-rule:evenodd;stroke:#000000;stroke-width:0.87379962;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1" />
+      <path
+         sodipodi:nodetypes="cccccccccccc"
+         inkscape:connector-curvature="0"
+         id="path4745"
+         d="m -646.69902,611.50192 -79.00757,0 c -5.32157,0.16679 -6.94386,4.08162 -6.91732,11.98114 l 0,45.43998 85.97537,0 0,-7.07362 -5.78092,0 c -1.41482,0 -2.54544,-1.13579 -2.54098,-2.93674 l 0,-36.99862 c 0.0228,-1.71464 0.26476,-2.99382 2.39387,-2.99382 l 5.85448,0 z"
+         style="fill:#617fff;fill-opacity:0.49019608;fill-rule:evenodd;stroke:#617fff;stroke-width:1.63500068;stroke-linecap:round;stroke-linejoin:round;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1" />
+      <path
+         style="fill:#617fff;fill-opacity:0.49019608;fill-rule:evenodd;stroke:#617fff;stroke-width:1.63500068;stroke-linecap:round;stroke-linejoin:round;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1"
+         d="m -630.47815,611.50192 79.00757,0 c 5.32158,0.16679 6.94386,4.08162 6.91732,11.98114 l 0,45.43998 -85.97537,0 0,-7.07362 5.78092,0 c 1.41482,0 2.54544,-1.13579 2.54098,-2.93674 l 0,-36.99862 c -0.0228,-1.71464 -0.26476,-2.99382 -2.39387,-2.99382 l -5.85448,0 z"
+         id="path4766"
+         inkscape:connector-curvature="0"
+         sodipodi:nodetypes="cccccccccccc" />
+      <rect
+         ry="7.3555903"
+         rx="7.3555903"
+         y="620.00159"
+         x="-645.80945"
+         height="39.42598"
+         width="15.593853"
+         id="rect4768"
+         style="opacity:1;fill:#617fff;fill-opacity:0.49019608;stroke:#617fff;stroke-width:1.63500068;stroke-linecap:round;stroke-linejoin:round;stroke-miterlimit:4;stroke-dasharray:none;stroke-dashoffset:0;stroke-opacity:1" />
+      <path
+         style="fill:none;fill-rule:evenodd;stroke:#000000;stroke-width:1.5;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1"
+         d="m -644.91259,651.46192 -6.56599,0.12226 0,106.78495 6.87951,-0.023"
+         id="path8458"
+         inkscape:connector-curvature="0"
+         sodipodi:nodetypes="cccc" />
+      <text
+         xml:space="preserve"
+         style="font-style:normal;font-weight:normal;font-size:14.765769px;line-height:125%;font-family:sans-serif;text-align:center;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1"
+         x="-703.82648"
+         y="718.50195"
+         id="text8466"
+         sodipodi:linespacing="125%"><tspan
+           sodipodi:role="line"
+           id="tspan8468"
+           x="-703.82648"
+           y="718.50195">Button 1</tspan><tspan
+           id="tspan5409"
+           sodipodi:role="line"
+           x="-703.82648"
+           y="736.95917">(LMB)</tspan></text>
+      <text
+         sodipodi:linespacing="125%"
+         id="text5405"
+         y="717.49182"
+         x="-582.11389"
+         style="font-style:normal;font-weight:normal;font-size:14.765769px;line-height:125%;font-family:sans-serif;text-align:center;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1"
+         xml:space="preserve"><tspan
+           y="717.49182"
+           x="-582.11389"
+           id="tspan5407"
+           sodipodi:role="line">Button 2</tspan><tspan
+           id="tspan5411"
+           y="735.94904"
+           x="-582.11389"
+           sodipodi:role="line">(RMB)</tspan></text>
+      <path
+         sodipodi:nodetypes="cccc"
+         inkscape:connector-curvature="0"
+         id="path5413"
+         d="m -644.66005,640.0977 -12.12183,0.12226 0,139.86744 12.81415,-0.023"
+         style="fill:none;fill-rule:evenodd;stroke:#000000;stroke-width:1.5;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1" />
+      <path
+         style="fill:none;fill-rule:evenodd;stroke:#000000;stroke-width:1.5;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1"
+         d="m -644.91259,627.47079 -17.42513,0.12226 0,171.18217 18.36999,0.0243"
+         id="path5415"
+         inkscape:connector-curvature="0"
+         sodipodi:nodetypes="cccc" />
+      <text
+         xml:space="preserve"
+         style="font-style:normal;font-weight:normal;font-size:14.765769px;line-height:125%;font-family:sans-serif;text-align:center;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1"
+         x="-594.89044"
+         y="785.26086"
+         id="text5417"
+         sodipodi:linespacing="125%"><tspan
+           sodipodi:role="line"
+           x="-594.89044"
+           y="785.26086"
+           id="tspan5421">Click: Button 3</tspan></text>
+      <text
+         sodipodi:linespacing="125%"
+         id="text5425"
+         y="803.3548"
+         x="-592.46796"
+         style="font-style:normal;font-weight:normal;font-size:14.765769px;line-height:125%;font-family:sans-serif;text-align:center;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1"
+         xml:space="preserve"><tspan
+           id="tspan5427"
+           y="803.3548"
+           x="-592.46796"
+           sodipodi:role="line">Down: Button 5</tspan></text>
+      <text
+         sodipodi:linespacing="125%"
+         id="text5429"
+         y="763.70624"
+         x="-601.84076"
+         style="font-style:normal;font-weight:normal;font-size:14.765769px;line-height:125%;font-family:sans-serif;text-align:center;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1"
+         xml:space="preserve"><tspan
+           id="tspan5431"
+           y="763.70624"
+           x="-601.84076"
+           sodipodi:role="line">Up: Button 4</tspan></text>
+      <path
+         sodipodi:nodetypes="cc"
+         inkscape:connector-curvature="0"
+         id="path5433"
+         d="m -705.40715,646.22703 0,58.57067"
+         style="fill:none;fill-rule:evenodd;stroke:#000000;stroke-width:1.5;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1" />
+      <path
+         style="fill:none;fill-rule:evenodd;stroke:#000000;stroke-width:1.5;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1"
+         d="m -582.19286,646.22703 0,58.57067"
+         id="path5435"
+         inkscape:connector-curvature="0"
+         sodipodi:nodetypes="cc" />
+      <circle
+         r="2.3214285"
+         cy="703.61224"
+         cx="-705.53571"
+         id="path5437"
+         style="opacity:1;fill:#000000;fill-opacity:1;stroke:none;stroke-width:1.75;stroke-linecap:round;stroke-linejoin:round;stroke-miterlimit:4;stroke-dasharray:none;stroke-dashoffset:0;stroke-opacity:1" />
+      <circle
+         style="opacity:1;fill:#000000;fill-opacity:1;stroke:none;stroke-width:1.75;stroke-linecap:round;stroke-linejoin:round;stroke-miterlimit:4;stroke-dasharray:none;stroke-dashoffset:0;stroke-opacity:1"
+         id="circle5439"
+         cx="-705.44647"
+         cy="646.91583"
+         r="2.3214285" />
+      <circle
+         r="2.3214285"
+         cy="646.02295"
+         cx="-582.23218"
+         id="circle5441"
+         style="opacity:1;fill:#000000;fill-opacity:1;stroke:none;stroke-width:1.75;stroke-linecap:round;stroke-linejoin:round;stroke-miterlimit:4;stroke-dasharray:none;stroke-dashoffset:0;stroke-opacity:1" />
+      <circle
+         style="opacity:1;fill:#000000;fill-opacity:1;stroke:none;stroke-width:1.75;stroke-linecap:round;stroke-linejoin:round;stroke-miterlimit:4;stroke-dasharray:none;stroke-dashoffset:0;stroke-opacity:1"
+         id="circle5443"
+         cx="-582.05359"
+         cy="704.41583"
+         r="2.3214285" />
+      <circle
+         style="opacity:1;fill:#000000;fill-opacity:1;stroke:none;stroke-width:1.75;stroke-linecap:round;stroke-linejoin:round;stroke-miterlimit:4;stroke-dasharray:none;stroke-dashoffset:0;stroke-opacity:1"
+         id="circle5445"
+         cx="-643.66077"
+         cy="627.63007"
+         r="2.3214285" />
+      <circle
+         r="2.3214285"
+         cy="639.95148"
+         cx="-643.66077"
+         id="circle5447"
+         style="opacity:1;fill:#000000;fill-opacity:1;stroke:none;stroke-width:1.75;stroke-linecap:round;stroke-linejoin:round;stroke-miterlimit:4;stroke-dasharray:none;stroke-dashoffset:0;stroke-opacity:1" />
+      <circle
+         style="opacity:1;fill:#000000;fill-opacity:1;stroke:none;stroke-width:1.75;stroke-linecap:round;stroke-linejoin:round;stroke-miterlimit:4;stroke-dasharray:none;stroke-dashoffset:0;stroke-opacity:1"
+         id="circle5449"
+         cx="-643.66077"
+         cy="651.55859"
+         r="2.3214285" />
+      <circle
+         r="2.3214285"
+         cy="758.34442"
+         cx="-645.08929"
+         id="circle5451"
+         style="opacity:1;fill:#000000;fill-opacity:1;stroke:none;stroke-width:1.75;stroke-linecap:round;stroke-linejoin:round;stroke-miterlimit:4;stroke-dasharray:none;stroke-dashoffset:0;stroke-opacity:1" />
+      <circle
+         style="opacity:1;fill:#000000;fill-opacity:1;stroke:none;stroke-width:1.75;stroke-linecap:round;stroke-linejoin:round;stroke-miterlimit:4;stroke-dasharray:none;stroke-dashoffset:0;stroke-opacity:1"
+         id="circle5453"
+         cx="-645.08929"
+         cy="779.77301"
+         r="2.3214285" />
+      <circle
+         r="2.3214285"
+         cy="798.88013"
+         cx="-645.08929"
+         id="circle5455"
+         style="opacity:1;fill:#000000;fill-opacity:1;stroke:none;stroke-width:1.75;stroke-linecap:round;stroke-linejoin:round;stroke-miterlimit:4;stroke-dasharray:none;stroke-dashoffset:0;stroke-opacity:1" />
+    </g>
+  </g>
+</svg>
diff --git a/mouse.c b/mouse.c
index 57c4a8ba5..272b12adc 100644
--- a/mouse.c
+++ b/mouse.c
@@ -19,7 +19,39 @@
  *
  */
 
-/** awesome mouse API
+/** awesome mouse API.
+ *
+ * The mouse buttons are represented as index. The common ones are:
+ *
+ * ![Client geometry](../images/mouse.svg)
+ *
+ * It is possible to be notified of mouse events by connecting to various
+ * `client`, `widget`s and `wibox` signals:
+ *
+ *  * `mouse::enter`
+ *  * `mouse::leave`
+ *  * `mouse::press`
+ *  * `mouse::release`
+ *  * `mouse::move`
+ *
+ * It is also possible to add generic mouse button callbacks for `client`s,
+ * `wiboxe`s and the `root` window. Those are set in the default `rc.lua` as such:
+ *
+ * **root**:
+ *
+ *    root.buttons(awful.util.table.join(
+ *        awful.button({ }, 3, function () mymainmenu:toggle() end),
+ *        awful.button({ }, 4, awful.tag.viewnext),
+ *        awful.button({ }, 5, awful.tag.viewprev)
+ *    ))
+ *
+ * **client**:
+ *
+ *    clientbuttons = awful.util.table.join(
+ *        awful.button({ }, 1, function (c) client.focus = c; c:raise() end),
+ *        awful.button({ modkey }, 1, awful.mouse.client.move),
+ *        awful.button({ modkey }, 3, awful.mouse.client.resize)
+ *    )
  *
  * See also `mousegrabber`
  *