diff --git a/library/Graphite/GraphiteQuery.php b/library/Graphite/GraphiteQuery.php
index ee90806..65bf05d 100644
--- a/library/Graphite/GraphiteQuery.php
+++ b/library/Graphite/GraphiteQuery.php
@@ -5,7 +5,27 @@ namespace Icinga\Module\Graphite;
 use Icinga\Module\Graphite\GraphiteWeb;
 use Icinga\Web\Url;
 
-
+/**
+ * Graphite query
+ * ==============
+ *
+ * Usage
+ * -----
+ * Constructor expects a GraphiteWeb instance. To make things easier, this
+ * ...
+ * <code>
+ * $query = $graphiteweb->select();
+ * </code>
+ *
+ * Filtering
+ * ---------
+ * <code>
+ * $query->from('base.$host.$service.$metric')
+ *       ->where('host', 'www1')
+ *       ->where('service', 'ping');
+ * </code>
+ *
+ */
 class GraphiteQuery
 {
     protected $web;
@@ -14,11 +34,21 @@ class GraphiteQuery
 
     protected $searchPattern;
 
+    /**
+     * Construct a new query
+     *
+     * @param GraphiteWeb $web Graphite webapp instance
+     */
     public function __construct(GraphiteWeb $web)
     {
         $this->web = $web;
     }
 
+    /**
+     * Set the base pattern for your query
+     *
+     * @return self
+     */
     public function from($base, $pattern = null)
     {
         if (is_array($base)) {
@@ -37,6 +67,71 @@ class GraphiteQuery
         return $this;
     }
 
+    /**
+     * Add a filter
+     *
+     * @param string $colum  Virtual column we are going to filter for
+     * @param string $search Search string
+     *
+     * @return self
+     */
+    public function where($column, $search)
+    {
+        $this->search = $this->replace($this->search, $column, $search);
+        return $this;
+    }
+
+    /**
+     * TODO: rename to getCharts
+     */
+    public function getImages(GraphTemplate $template)
+    {
+        $charts = array();
+
+        foreach ($this->listMetrics() as $metric) {
+            $vars = GraphiteUtil::extractVars($metric, $this->getSearchPattern());
+            $charts[] = new GraphiteChart($this->web, $template, $metric, $vars);
+        }
+
+        return $charts;
+    }
+
+    /**
+     * List all metrics fitting this query
+     *
+     */
+    public function listMetrics($filterString = null)
+    {
+        if ($filterString === null) {
+            $filterString = $this->toFilterString();
+        }
+
+        $metrics = $this->web->listMetrics($filterString);
+        asort($metrics);
+        return $metrics;
+    }
+
+    /**
+     * Retrieve a distinct list of values fitting a given placeholder in our
+     * search pattern
+     *
+     * Example
+     * -------
+     * This example retrieves all distinct services available on any host
+     * belonging to our customer "Icinga".
+     *
+     * <code>
+     * $icingaHosts = $graphite
+     *     ->select()
+     *     ->from('base.$customer.$host.$service.$metric')
+     *     ->where('customer', 'icinga')
+     *     ->listMetrics('service');
+     * </code>
+     *
+     * @param  string $placeholder The placeholder we are interested in
+     *
+     * @return array
+     */
     public function listDistinct($placeholder)
     {
         $search = $this->getSearchPattern();
@@ -74,6 +169,13 @@ class GraphiteQuery
         return $distinct;
     }
 
+    /**
+     * Get our search pattern
+     *
+     * TODO: example
+     *
+     * @return string
+     */
     public function getSearchPattern()
     {
         return $this->searchPattern;
@@ -88,12 +190,6 @@ class GraphiteQuery
         );
     }
 
-    public function where($column, $search)
-    {
-        $this->search = $this->replace($this->search, $column, $search);
-        return $this;
-    }
-
     /**
      * Replace all variables ($some_thing) with an asterisk
      *
@@ -111,27 +207,4 @@ class GraphiteQuery
     {
         return $this->replaceRemainingVariables($this->search);
     }
-
-    public function getImages(GraphTemplate $template)
-    {
-        $charts = array();
-
-        foreach ($this->listMetrics() as $metric) {
-            $vars = GraphiteUtil::extractVars($metric, $this->getSearchPattern());
-            $charts[] = new GraphiteChart($this->web, $template, $metric, $vars);
-        }
-
-        return $charts;
-    }
-
-    public function listMetrics($filterString = null)
-    {
-        if ($filterString === null) {
-            $filterString = $this->toFilterString();
-        }
-
-        $metrics = $this->web->listMetrics($filterString);
-        asort($metrics);
-        return $metrics;
-    }
 }