refs #5820 added documentation and improved code

1 files changed, 80 insertions, 4 deletions

diff --git a/core/Plugin/Segment.php b/core/Plugin/Segment.php
index 4169d1453c..4281495a35 100644
--- a/core/Plugin/Segment.php
+++ b/core/Plugin/Segment.php
@@ -9,12 +9,36 @@
 namespace Piwik\Plugin;
 
 /**
+ * Creates a new segment that can be used for instance within the {@link \Piwik\Columns\Dimension::configureSegment()}
+ * method. Make sure to set at least the following values: {@link setName()}, {@link setSegment()},
+ * {@link setSqlSegment()}, {@link setType()} and {@link setCategory()}. If you are using a segment in the context of a
+ * dimension the type and the SQL segment is usually set for you automatically.
+ *
+ * Example:
+ * ```
+ $segment = new \Piwik\Plugin\Segment();
+ $segment->setType(\Piwik\Plugin\Segment::TYPE_DIMENSION);
+ $segment->setName('General_EntryKeyword');
+ $segment->setCategory('General_Visit');
+ $segment->setSegment('entryKeyword');
+ $segment->setSqlSegment('log_visit.entry_keyword');
+ $segment->setAcceptedValues('Any keywords people search for on your website such as "help" or "imprint"');
+ ```
  * @api
  * @since 2.5.0
  */
 class Segment
 {
+    /**
+     * Segment type 'dimension'. Can be used along with {@link setType()}.
+     * @api
+     */
     const TYPE_DIMENSION = 'dimension';
+
+    /**
+     * Segment type 'metric'. Can be used along with {@link setType()}.
+     * @api
+     */
     const TYPE_METRIC = 'metric';
 
     private $type;
@@ -27,26 +51,42 @@ class Segment
     private $acceptValues;
     private $permission;
 
-    public function __construct()
+    /**
+     * @ignore
+     */
+    final public function __construct()
     {
         $this->init();
     }
 
+    /**
+     * Here you can initialize this segment and set any default values. It is called directly after the object is
+     * created.
+     * @api
+     */
     protected function init()
     {
 
     }
 
     /**
-     * @param string $acceptValues
+     * Here you should explain which values are accepted/useful for your segment, for example:
+     * "1, 2, 3, etc." or "comcast.net, proxad.net, etc.". If the value needs any special encoding you should mention
+     * this as well. For example "Any URL including protocol. The URL must be URL encoded."
+     *
+     * @param string $acceptedValues
+     * @api
      */
-    public function setAcceptedValues($acceptValues)
+    public function setAcceptedValues($acceptedValues)
     {
-        $this->acceptValues = $acceptValues;
+        $this->acceptValues = $acceptedValues;
     }
 
     /**
+     * Set (overwrite) the category this segment belongs to. It should be a translation key such as 'General_Actions'
+     * or 'General_Visit'.
      * @param string $category
+     * @api
      */
     public function setCategory($category)
     {
@@ -54,7 +94,10 @@ class Segment
     }
 
     /**
+     * Set (overwrite) the segment display name. This name will be visible in the API and the UI. It should be a
+     * translation key such as 'Actions_ColumnEntryPageTitle' or 'UserSettings_ColumnResolution'.
      * @param string $name
+     * @api
      */
     public function setName($name)
     {
@@ -62,7 +105,11 @@ class Segment
     }
 
     /**
+     * Set (overwrite) the name of the segment. The name should be lower case first and has to be unique. The segment
+     * name defined here needs to be set in the URL to actually apply this segment. Eg if the segment is 'searches'
+     * you need to set "&segment=searches>0" in the UI.
      * @param string $segment
+     * @api
      */
     public function setSegment($segment)
     {
@@ -70,7 +117,15 @@ class Segment
     }
 
     /**
+     * Sometimes you want users to set values that differ from the way they are actually stored. For instance if you
+     * want to allow to filter by any URL than you might have to resolve this URL to an action id. Or a country name
+     * maybe has to be mapped to a 2 letter country code. You can do this by specifing either a callable such as
+     * `array('Classname', 'methodName')` or by passing a closure. There will be four values passed to the given closure
+     * or callable: `string $valueToMatch`, `string $segment` (see {@link setSegment()}), `string $matchType`
+     * (eg SegmentExpression::MATCH_EQUAL or any other match constant of this class) and `$segmentName`.
+     *
      * @param string|\Closure $sqlFilter
+     * @api
      */
     public function setSqlFilter($sqlFilter)
     {
@@ -78,7 +133,12 @@ class Segment
     }
 
     /**
+     * Similar to {@link setSqlFilter()} you can map a given segment value to another value. For instance you could map
+     * "new" to 0, 'returning' to 1 and any other value to '2'. You can either define a callable or a closure. There
+     * will be only one value passed to the closure or callable which contains the value a user has set for this
+     * segment. This callback is called shortly before {@link setSqlFilter()}.
      * @param string|array $sqlFilterValue
+     * @api
      */
     public function setSqlFilterValue($sqlFilterValue)
     {
@@ -86,7 +146,11 @@ class Segment
     }
 
     /**
+     * Defines to which column in the MySQL database the segment belongs: 'mytablename.mycolumnname'. Eg
+     * 'log_visit.idsite'. When a segment is applied the given or filtered value will be compared with this column.
+     *
      * @param string $sqlSegment
+     * @api
      */
     public function setSqlSegment($sqlSegment)
     {
@@ -95,6 +159,7 @@ class Segment
 
     /**
      * @return string
+     * @ignore
      */
     public function getSqlSegment()
     {
@@ -102,7 +167,9 @@ class Segment
     }
 
     /**
+     * Set (overwrite) the type of this segment which is usually either a 'dimension' or a 'metric'.
      * @param string $type See constansts TYPE_*
+     * @api
      */
     public function setType($type)
     {
@@ -111,6 +178,7 @@ class Segment
 
     /**
      * @return string
+     * @ignore
      */
     public function getType()
     {
@@ -118,13 +186,21 @@ class Segment
     }
 
     /**
+     * You can restrict the access to this segment by passing a boolean `false`. For instance if you want to make
+     * a certain segment only available to users having super user access you could do the following:
+     * `$segment->setPermission(Piwik::hasUserSuperUserAccess());`
      * @param bool $permission
+     * @api
      */
     public function setPermission($permission)
     {
         $this->permission = $permission;
     }
 
+    /**
+     * @return array
+     * @ignore
+     */
     public function toArray()
     {
         $segment = array(