Skip to content

Commit 06bb25e

Browse files
sgiehlsgiehl
committed
added/fixed doc blocks
git-svn-id: http://dev.piwik.org/svn/trunk@6353 59fd770c-687e-43c8-a1e3-f5a4ff64c105
1 parent 90ae9e1 commit 06bb25e

57 files changed

Lines changed: 1309 additions & 488 deletions

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎core/API/DataTableGenericFilter.php‎

Lines changed: 13 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -17,12 +17,22 @@
1717
class Piwik_API_DataTableGenericFilter
1818
{
1919
private static $genericFiltersInfo = null;
20-
20+
21+
/**
22+
* Constructor
23+
*
24+
* @param $request
25+
*/
2126
function __construct( $request )
2227
{
2328
$this->request = $request;
2429
}
2530

31+
/**
32+
* Filters the given data table
33+
*
34+
* @param Piwik_DataTable $table
35+
*/
2636
public function filter($table)
2737
{
2838
$this->applyGenericFilters($table);
@@ -38,7 +48,7 @@ public function filter($table)
3848
* 3 - Filter that keep only a subset of the results
3949
* 4 - Presentation filters
4050
*
41-
* @return array See the code for spec
51+
* @return array See the code for spec
4252
*/
4353
public static function getGenericFiltersInformation()
4454
{
@@ -88,7 +98,7 @@ public static function getGenericFiltersInformation()
8898
* Apply generic filters to the DataTable object resulting from the API Call.
8999
* Disable this feature by setting the parameter disable_generic_filters to 1 in the API call request.
90100
*
91-
* @param Piwik_DataTable
101+
* @param Piwik_DataTable $datatable
92102
* @return bool
93103
*/
94104
protected function applyGenericFilters($datatable)

‎core/API/DataTableManipulator.php‎

Lines changed: 21 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -32,7 +32,14 @@ abstract class Piwik_API_DataTableManipulator
3232
protected $request;
3333

3434
private $apiMethodForSubtable;
35-
35+
36+
/**
37+
* Constructor
38+
*
39+
* @param bool $apiModule
40+
* @param bool $apiMethod
41+
* @param array $request
42+
*/
3643
public function __construct($apiModule=false, $apiMethod=false, $request=array()) {
3744
$this->apiModule = $apiModule;
3845
$this->apiMethod = $apiMethod;
@@ -43,7 +50,8 @@ public function __construct($apiModule=false, $apiMethod=false, $request=array()
4350
* This method can be used by subclasses to iterate over data tables that might be
4451
* data table arrays. It calls back the template method self::doManipulate for each table.
4552
* This way, data table arrays can be handled in a transparent fashion.
46-
* @param Piwik_DataTable_Array|Piwik_DataTable $dataTable
53+
*
54+
* @param Piwik_DataTable_Array|Piwik_DataTable $dataTable
4755
* @throws Exception
4856
* @return Piwik_DataTable_Array|Piwik_DataTable
4957
*/
@@ -82,8 +90,9 @@ protected function manipulate($dataTable) {
8290

8391
/**
8492
* Template method called from self::manipulate
85-
* @param Piwik_DataTable $dataTable
86-
* @param bool|string $date
93+
*
94+
* @param Piwik_DataTable $dataTable
95+
* @param bool|string $date
8796
* @return
8897
*/
8998
protected abstract function doManipulate(Piwik_DataTable $dataTable, $date=false);
@@ -92,8 +101,8 @@ protected abstract function doManipulate(Piwik_DataTable $dataTable, $date=false
92101
* Load the subtable for a row.
93102
* Returns null if none is found.
94103
*
95-
* @param Piwik_Datatable_Row $row
96-
* @param bool $date
104+
* @param Piwik_Datatable_Row $row
105+
* @param bool|string $date
97106
* @throws Exception
98107
* @return Piwik_DataTable
99108
*/
@@ -144,12 +153,17 @@ protected function loadSubtable($row, $date=false) {
144153
* In this method, subclasses can clean up the request array for loading subtables
145154
* in order to make Piwik_API_ResponseBuilder behave correctly (e.g. not trigger the
146155
* manipulator again).
156+
*
147157
* @param $request
148158
* @return
149159
*/
150160
protected abstract function manipulateSubtableRequest(&$request);
151161

152-
/** Extract the API method for loading subtables from the meta data */
162+
/**
163+
* Extract the API method for loading subtables from the meta data
164+
*
165+
* @return string
166+
*/
153167
private function getApiMethodForSubtable()
154168
{
155169
if (!$this->apiMethodForSubtable)

‎core/API/DataTableManipulator/Flattener.php‎

Lines changed: 18 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -39,7 +39,11 @@ public function includeAggregateRows()
3939
* @var string
4040
*/
4141
public $recursiveLabelSeparator = ' - ';
42-
42+
43+
/**
44+
* @param Piwik_DataTable $dataTable
45+
* @return Piwik_DataTable|Piwik_DataTable_Array
46+
*/
4347
public function flatten($dataTable)
4448
{
4549
if ($this->apiModule == 'Actions' || $this->apiMethod == 'getWebsites')
@@ -53,8 +57,9 @@ public function flatten($dataTable)
5357
/**
5458
* Template method called from self::manipulate.
5559
* Flatten each data table.
56-
* @param Piwik_DataTable $dataTable
57-
* @param bool $date
60+
*
61+
* @param Piwik_DataTable $dataTable
62+
* @param bool $date
5863
* @return Piwik_DataTable
5964
*/
6065
protected function doManipulate(Piwik_DataTable $dataTable, $date = false)
@@ -66,7 +71,14 @@ protected function doManipulate(Piwik_DataTable $dataTable, $date = false)
6671
}
6772
return $newDataTable;
6873
}
69-
74+
75+
/**
76+
* @param Piwik_DataTable_Row $row
77+
* @param Piwik_DataTable $dataTable
78+
* @param string $date
79+
* @param string $labelPrefix
80+
* @param bool $parentLogo
81+
*/
7082
private function flattenRow(Piwik_DataTable_Row $row, Piwik_DataTable $dataTable, $date,
7183
$labelPrefix = '', $parentLogo = false) {
7284

@@ -117,7 +129,8 @@ private function flattenRow(Piwik_DataTable_Row $row, Piwik_DataTable $dataTable
117129

118130
/**
119131
* Remove the flat parameter from the subtable request
120-
* @param $request
132+
*
133+
* @param array $request
121134
*/
122135
protected function manipulateSubtableRequest(&$request)
123136
{

‎core/API/DataTableManipulator/LabelFilter.php‎

Lines changed: 18 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -41,8 +41,8 @@ class Piwik_API_DataTableManipulator_LabelFilter extends Piwik_API_DataTableMani
4141
* for the recursive search. If the label is not recursive, these parameters
4242
* are not needed.
4343
*
44-
* @param string $label the label to search for
45-
* @param Piwik_DataTable $dataTable the data table to be filtered
44+
* @param string $label the label to search for
45+
* @param Piwik_DataTable $dataTable the data table to be filtered
4646
* @return Piwik_DataTable
4747
*/
4848
public function filter($label, $dataTable)
@@ -82,8 +82,9 @@ public function filter($label, $dataTable)
8282
/**
8383
* This method is called from parent::manipulate for each Piwik_DataTable.
8484
* It starts the recursive descend and builds a table with one or zero rows.
85-
* @param Piwik_DataTable $dataTable
86-
* @param bool $date
85+
*
86+
* @param Piwik_DataTable $dataTable
87+
* @param bool $date
8788
* @return Piwik_DataTable
8889
*/
8990
protected function doManipulate(Piwik_DataTable $dataTable, $date=false)
@@ -99,10 +100,11 @@ protected function doManipulate(Piwik_DataTable $dataTable, $date=false)
99100

100101
/**
101102
* Method for the recursive descend
102-
* @param $labelParts
103-
* @param $dataTable
104-
* @param bool $date
105-
* @return Piwik_DataTable_Row | false
103+
*
104+
* @param array $labelParts
105+
* @param Piwik_DataTable $dataTable
106+
* @param bool $date
107+
* @return Piwik_DataTable_Row|false
106108
*/
107109
private function doFilterRecursiveDescend($labelParts, $dataTable, $date=false)
108110
{
@@ -140,16 +142,21 @@ private function doFilterRecursiveDescend($labelParts, $dataTable, $date=false)
140142

141143
return $this->doFilterRecursiveDescend($labelParts, $subTable, $date);
142144
}
143-
145+
146+
/**
147+
* Clean up request for Piwik_API_ResponseBuilder to behave correctly
148+
*
149+
* @param $request
150+
*/
144151
protected function manipulateSubtableRequest(&$request)
145152
{
146-
// Clean up request for Piwik_API_ResponseBuilder to behave correctly
147153
unset($request['label']);
148154
}
149155

150156
/**
151157
* Use variations of the label to make it easier to specify the desired label
152-
* @param $label
158+
*
159+
* @param string $label
153160
* @return array
154161
*/
155162
private function getLabelVariations($label) {

‎core/API/DocumentationGenerator.php‎

Lines changed: 8 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -41,8 +41,8 @@ public function __construct()
4141
* For each module it will return a mini help with the method names, parameters to give,
4242
* links to get the result in Xml/Csv/etc
4343
*
44-
* @param bool $outputExampleUrls
45-
* @param string $prefixUrls
44+
* @param bool $outputExampleUrls
45+
* @param string $prefixUrls
4646
* @return string
4747
*/
4848
public function getAllInterfaceString( $outputExampleUrls = true, $prefixUrls = '' )
@@ -121,9 +121,9 @@ public function getAllInterfaceString( $outputExampleUrls = true, $prefixUrls =
121121
* It will export links to XML, CSV, HTML, JSON, PHP, etc.
122122
* It will not export links for methods such as deleteSite or deleteUser
123123
*
124-
* @param string $class the class
125-
* @param string $methodName the method
126-
* @param array $parametersToSet
124+
* @param string $class the class
125+
* @param string $methodName the method
126+
* @param array $parametersToSet parameters to set
127127
* @return string|false when not possible
128128
*/
129129
public function getExampleUrl($class, $methodName, $parametersToSet = array())
@@ -213,9 +213,9 @@ public function getExampleUrl($class, $methodName, $parametersToSet = array())
213213
/**
214214
* Returns the methods $class.$name parameters (and default value if provided) as a string.
215215
*
216-
* @param string The class name
217-
* @param string The method name
218-
* @return string For example "(idSite, period, date = 'today')"
216+
* @param string $class The class name
217+
* @param string $name The method name
218+
* @return string For example "(idSite, period, date = 'today')"
219219
*/
220220
public function getParametersString($class, $name)
221221
{

‎core/API/Request.php‎

Lines changed: 15 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -39,7 +39,13 @@
3939
class Piwik_API_Request
4040
{
4141
protected $request = null;
42-
42+
43+
/**
44+
* Returns the request array as string
45+
*
46+
* @param string|array $request
47+
* @return array|null
48+
*/
4349
static public function getRequestArrayFromString($request)
4450
{
4551
$defaultRequest = $_GET + $_POST;
@@ -76,11 +82,11 @@ static public function getRequestArrayFromString($request)
7682

7783
/**
7884
* Constructs the request to the API, given the request url
79-
*
80-
* @param string GET request that defines the API call (must at least contain a "method" parameter)
81-
* Example: method=UserSettings.getWideScreen&idSite=1&date=yesterday&period=week&format=xml
82-
* If a request is not provided, then we use the $_GET and $_POST superglobal and fetch
83-
* the values directly from the HTTP GET query.
85+
*
86+
* @param string $request GET request that defines the API call (must at least contain a "method" parameter)
87+
* Example: method=UserSettings.getWideScreen&idSite=1&date=yesterday&period=week&format=xml
88+
* If a request is not provided, then we use the $_GET and $_POST superglobal and fetch
89+
* the values directly from the HTTP GET query.
8490
*/
8591
function __construct($request = null)
8692
{
@@ -94,7 +100,7 @@ function __construct($request = null)
94100
* It then calls the API Proxy which will call the requested method.
95101
*
96102
* @throws Piwik_FrontController_PluginDeactivatedException
97-
* @return mixed The data resulting from the API call
103+
* @return mixed The data resulting from the API call
98104
*/
99105
public function process()
100106
{
@@ -133,7 +139,7 @@ public function process()
133139
* the current session will be authenticated using this token_auth.
134140
* It will overwrite the previous Auth object.
135141
*
136-
* @param array $request If null, uses the default request ($_GET)
142+
* @param array $request If null, uses the default request ($_GET)
137143
* @return void
138144
*/
139145
static public function reloadAuthUsingTokenAuth($request = null)
@@ -151,7 +157,7 @@ static public function reloadAuthUsingTokenAuth($request = null)
151157
/**
152158
* Returns array( $class, $method) from the given string $class.$method
153159
*
154-
* @param $parameter
160+
* @param string $parameter
155161
* @throws Exception
156162
* @return array
157163
*/

0 commit comments

Comments
 (0)