From e231ef8061dd655882fc5241a6844b5b1f74f83d Mon Sep 17 00:00:00 2001
From: Johannes Meyer <johannes.meyer@netways.de>
Date: Tue, 28 Jul 2015 12:04:16 +0200
Subject: [PATCH] SortBox: Fix some documenation and code style issues

---
 library/Icinga/Web/Widget/SortBox.php | 44 +++++++++++++++------------
 1 file changed, 24 insertions(+), 20 deletions(-)

diff --git a/library/Icinga/Web/Widget/SortBox.php b/library/Icinga/Web/Widget/SortBox.php
index 9d0945394..7a09c2f36 100644
--- a/library/Icinga/Web/Widget/SortBox.php
+++ b/library/Icinga/Web/Widget/SortBox.php
@@ -12,22 +12,17 @@ use Icinga\Web\Request;
 /**
  * SortBox widget
  *
- * The "SortBox" Widget allows you to create a generic sort input for sortable views. It automatically creates a form
- * containing a select box with all sort options and a dropbox with the sort direction. It also handles automatic
- * submission of sorting changes and draws an additional submit button when JavaScript is disabled.
+ * The "SortBox" Widget allows you to create a generic sort input for sortable views. It automatically creates a select
+ * box with all sort options and a dropbox with the sort direction. It also handles automatic submission of sorting
+ * changes and draws an additional submit button when JavaScript is disabled.
  *
- * The constructor takes an string for the component name and an array containing the select options, where the key is
+ * The constructor takes a string for the component name and an array containing the select options, where the key is
  * the value to be submitted and the value is the label that will be shown. You then should call setRequest in order
  * to  make sure the form is correctly populated when a request with a sort parameter is being made.
  *
- * Example:
- *  <pre><code>
- *      $this->view->sortControl = new SortBox(
- *          $this->getRequest()->getActionName(),
- *          $columns
- *      );
- *      $this->view->sortControl->setRequest($this->getRequest());
- *  </code></pre>
+ * Call setQuery in case you'll do not want to handle URL parameters manually, but to automatically apply the user's
+ * chosen sort rules on the given sortable query. This will also allow the SortBox to display the user the correct
+ * default sort rules if the given query provides already some sort rules.
  */
 class SortBox extends AbstractWidget
 {
@@ -39,25 +34,25 @@ class SortBox extends AbstractWidget
     protected $sortFields;
 
     /**
-     * The name of the form that will be created
+     * The name used to uniquely identfy the forms being created
      *
      * @var string
      */
     protected $name;
 
     /**
-     * A request object used for initial form population
+     * The request to fetch sort rules from
      *
      * @var Request
      */
     protected $request;
 
     /**
-     * What to apply sort parameters on
+     * The query to apply sort rules on
      *
      * @var Sortable
      */
-    protected $query = null;
+    protected $query;
 
     /**
      * Create a SortBox with the entries from $sortFields
@@ -85,9 +80,9 @@ class SortBox extends AbstractWidget
     }
 
     /**
-     * Apply the parameters from the given request on this SortBox
+     * Set the request to fetch sort rules from
      *
-     * @param   Request     $request    The request to use for populating the form
+     * @param   Request     $request
      *
      * @return  $this
      */
@@ -98,9 +93,11 @@ class SortBox extends AbstractWidget
     }
 
     /**
-     * @param Sortable $query
+     * Set the query to apply sort rules on
      *
-     * @return $this
+     * @param   Sortable    $query
+     *
+     * @return  $this
      */
     public function setQuery(Sortable $query)
     {
@@ -108,6 +105,13 @@ class SortBox extends AbstractWidget
         return $this;
     }
 
+    /**
+     * Apply the sort rules from the given or current request on the query
+     *
+     * @param   Request     $request
+     *
+     * @return  $this
+     */
     public function handleRequest(Request $request = null)
     {
         if ($this->query !== null) {