Code cleanup (#556)

lib/Controller/AggregatorController.php

@@ -24,7 +24,6 @@
 namespace Volkszaehler\Controller;
 
 use Volkszaehler\Model;
-use Volkszaehler\Definition;
 
 /**
  * Aggregator controller
@@ -35,6 +34,9 @@
 class AggregatorController extends EntityController {
 	/**
 	 * Get aggregator
+	 * @param null $identifier
+	 * @return array
+	 * @throws \Exception
 	 */
 	public function get($identifier = NULL) {
 		$aggregator = parent::get($identifier);
@@ -54,6 +56,9 @@ public function get($identifier = NULL) {
 
 	/**
 	 * Create new aggregator or add entity to aggregator
+	 * @param null $identifier
+	 * @return array|Model\Aggregator
+	 * @throws \Exception
 	 */
 	public function add($identifier = NULL) {
 		if (isset($identifier)) {	// add entity to aggregator
@@ -88,6 +93,8 @@ public function add($identifier = NULL) {
 
 	/**
 	 * Delete Aggregator or remove entity from aggregator
+	 * @param $identifier
+	 * @return array|null
 	 */
 	public function delete($identifier) {
 		if (!isset($identifier))

lib/Controller/CapabilitiesController.php

@@ -23,8 +23,9 @@
 
 namespace Volkszaehler\Controller;
 
+use Doctrine\DBAL\Connection;
+
 use Volkszaehler\Router;
-use Volkszaehler\Model;
 use Volkszaehler\Util;
 use Volkszaehler\View;
 use Volkszaehler\Definition;
@@ -40,8 +41,11 @@ class CapabilitiesController extends Controller {
 
 	/**
 	 * Fast MyISAM/ InnoDB table count
+	 * @param Connection $conn
+	 * @param string $table
+	 * @return int Number of database rows
 	 */
-	private function sqlCount($conn, $table) {
+	private function sqlCount(Connection $conn, $table) {
 		$explain = $conn->fetchAssoc('EXPLAIN SELECT COUNT(id) FROM ' . $table . ' USE INDEX (PRIMARY)');
 		if (isset($explain['rows']))
 			// estimated for InnoDB
@@ -58,8 +62,11 @@ private function sqlCount($conn, $table) {
 
 	/**
 	 * Estimated table disk space
+	 * @param Connection $conn
+	 * @param string $table
+	 * @return mixed
 	 */
-	private function dbSize($conn, $table = null) {
+	private function dbSize(Connection $conn, $table = null) {
 		$sql = 'SELECT SUM(data_length + index_length) FROM information_schema.tables WHERE LOWER(table_schema) = LOWER(?)';
 		$params = array(Util\Configuration::read('db.dbname'));
 
@@ -73,6 +80,7 @@ private function dbSize($conn, $table = null) {
 
 	/**
 	 * @param string $section select specific sub section for output
+	 * @return array
 	 */
 	public function get($section = NULL) {
 		$capabilities = array();

lib/Controller/ChannelController.php

@@ -24,8 +24,6 @@
 namespace Volkszaehler\Controller;
 
 use Volkszaehler\Model;
-use Volkszaehler\Util;
-use Volkszaehler\Definition;
 
 /**
  * Channel controller
@@ -37,6 +35,9 @@ class ChannelController extends EntityController {
 
 	/**
 	 * Get channel
+	 * @param null $identifier
+	 * @return array
+	 * @throws \Exception
 	 */
 	public function get($identifier = NULL) {
 		$channel = parent::get($identifier);

lib/Controller/Controller.php

@@ -34,8 +34,6 @@
  * @author Steffen Vogel <info@steffenvogel.de>
  * @author Andreas Goetz <cpuidle@gmx.de>
  * @package default
- *
- * @todo Check how controllers can modify the response/headers
  */
 abstract class Controller {
 
@@ -89,7 +87,10 @@ public function getParameters() {
 	/**
 	 * Run operation
 	 *
-	 * @param string $operation runs the operation if class method is available
+	 * @param $op Operation to run
+	 * @param null $uuid Uuid to operate on
+	 * @return operation result
+	 * @throws \Exception
 	 */
 	public function run($op, $uuid = null) {
 		if (!method_exists($this, $op)) {
@@ -107,6 +108,8 @@ public function run($op, $uuid = null) {
 
 	/**
 	 * Helper function to convert single/multiple parameters to array format
+	 * @param $data
+	 * @return array
 	 */
 	protected static function makeArray($data) {
 		if (!is_array($data)) {

lib/Controller/DataController.php

@@ -53,6 +53,7 @@ public function __construct(Request $request, EntityManager $em, View $view) {
 	 * Query for data by given channel or group or multiple channels
 	 *
 	 * @param string|array uuid
+	 * @return array
 	 */
 	public function get($uuid) {
 		$from = $this->getParameters()->get('from');
@@ -78,6 +79,8 @@ public function get($uuid) {
 	 *
 	 * @todo deduplicate Model\Channel code
 	 * @param string|array uuid
+	 * @return array
+	 * @throws \Exception
 	 */
 	public function add($uuid) {
 		$channel = EntityController::factory($this->em, $uuid, true);
@@ -138,7 +141,9 @@ public function add($uuid) {
 	 * Delete tuples from single or multiple channels
 	 *
 	 * @todo deduplicate Model\Channel code
-	 * @param string|array uuid
+	 * @param string|array $uuids
+	 * @return array
+	 * @throws \Exception
 	 */
 	public function delete($uuids) {
 		$from = null;

lib/Controller/EntityController.php

@@ -23,7 +23,6 @@
 
 namespace Volkszaehler\Controller;
 
-use Symfony\Component\HttpFoundation\Request;
 use Doctrine\ORM\EntityManager;
 
 use Volkszaehler\Model;
@@ -47,7 +46,9 @@ class EntityController extends Controller {
 	/**
 	 * Get entity
 	 *
-	 * @param string $identifier
+	 * @param $uuids
+	 * @return array
+	 * @throws \Exception
 	 */
 	public function get($uuids) {
 		if (is_string($uuids)) { // single entity
@@ -79,10 +80,25 @@ public function get($uuids) {
 		}
 	}
 
+	/**
+	 * Return a single entity, potentially from cache
+	 * @param $uuid
+	 * @param bool $allowCache
+	 * @return mixed
+	 */
 	public function getSingleEntity($uuid, $allowCache = false) {
 		return self::factory($this->em, $uuid, $allowCache);
 	}
 
+	/**
+	 * Static entity factory- usable for scripting
+	 *
+	 * @param EntityManager $em
+	 * @param $uuid
+	 * @param bool $allowCache
+	 * @return mixed
+	 * @throws \Exception
+	 */
 	static function factory(EntityManager $em, $uuid, $allowCache = false) {
 		if (!Util\UUID::validate($uuid)) {
 			throw new \Exception('Invalid UUID: \'' . $uuid . '\'');
@@ -120,6 +136,8 @@ static function factory(EntityManager $em, $uuid, $allowCache = false) {
 
 	/**
 	 * Delete entity by uuid
+	 * @param $identifier
+	 * @throws \Exception
 	 */
 	public function delete($identifier) {
 		if (!($entity = $this->get($identifier)) instanceof Model\Entity) {
@@ -140,6 +158,9 @@ public function delete($identifier) {
 
 	/**
 	 * Edit entity properties
+	 * @param $identifier
+	 * @return array
+	 * @throws \Exception
 	 */
 	public function edit($identifier) {
 		if (!($entity = $this->get($identifier)) instanceof Model\Entity) {
@@ -161,6 +182,9 @@ public function edit($identifier) {
 
 	/**
 	 * Update/set/delete properties of entities
+	 * @param Model\Entity $entity
+	 * @param $parameters
+	 * @throws \Exception
 	 */
 	protected function setProperties(Model\Entity $entity, $parameters) {
 		foreach ($parameters as $key => $value) {
@@ -183,9 +207,8 @@ protected function setProperties(Model\Entity $entity, $parameters) {
 	}
 
 	/**
-	 * Filter entites by properties
+	 * Filter entities by properties
 	 *
-	 * @todo improve performance
 	 * @param array of property => value filters
 	 * @return array of entities
 	 */

lib/Controller/IotController.php

@@ -40,6 +40,13 @@ class IotController extends Controller {
 	 */
 	protected $ec;
 
+	/**
+	 * IotController constructor
+	 *
+	 * @param Request $request
+	 * @param EntityManager $em
+	 * @param View $view
+	 */
 	public function __construct(Request $request, EntityManager $em, View $view) {
 		parent::__construct($request, $em, $view);
 		$this->ec = new EntityController($request, $em);
@@ -48,7 +55,9 @@ public function __construct(Request $request, EntityManager $em, View $view) {
 	/**
 	 * Run operation
 	 *
-	 * @param string $operation runs the operation if class method is available
+	 * @param null $uuid
+	 * @return array
+	 * @throws \Exception
 	 */
 	public function get($uuid = null) {
 		if ($uuid === null || is_array($uuid) || strlen($uuid) < 32) {

lib/Interpreter/Interpreter.php

@@ -23,7 +23,6 @@
 
 namespace Volkszaehler\Interpreter;
 
-use Volkszaehler\Util;
 use Volkszaehler\Model;
 use Volkszaehler\Interpreter\SQL;
 use Doctrine\ORM;
@@ -65,10 +64,14 @@ abstract class Interpreter implements \IteratorAggregate {
 	/**
 	 * Constructor
 	 *
-	 * @param Channel $channel
-	 * @param EntityManager $em
+	 * @param Model\Channel $channel
+	 * @param ORM\EntityManager $em
 	 * @param integer $from timestamp in ms since 1970
 	 * @param integer $to timestamp in ms since 1970
+	 * @param null $tupleCount
+	 * @param null $groupBy
+	 * @param array $options
+	 * @throws \Exception
 	 */
 	public function __construct(Model\Channel $channel, ORM\EntityManager $em, $from, $to, $tupleCount = null, $groupBy = null, $options = array()) {
 		$this->channel = $channel;
@@ -132,7 +135,8 @@ abstract public function convertRawTuple($row);
 	/**
 	 * Check if option is specified
 	 *
-	 * @param  string  $str option name
+	 * @param  string $str option name
+	 * @return bool
 	 */
 	protected function hasOption($str) {
 		return in_array($str, $this->options);
@@ -172,10 +176,10 @@ public function getMax() {
 	}
 
 	/**
-	 * Get raw data
+	 * Get raw data from database
 	 *
-	 * @param string|integer $groupBy
-	 * @return Volkszaehler\DataIterator
+	 * @return DataIterator
+	 * @throws \Exception
 	 */
 	protected function getData() {
 		if (!$this->hasOption('exact')) {
@@ -255,6 +259,7 @@ protected function getData() {
 	 * @author Andreas Götz <cpuidle@gmx.de>
 	 * @param string $expression sql parameter
 	 * @return string grouped sql expression
+	 * @throws \Exception
 	 */
 	public static function groupExprSQL($expression) {
 		throw new \Exception('Derived classes must implement static function groupExprSQL.');
@@ -298,11 +303,10 @@ public static function buildDateTimeFilterSQL($from = NULL, $to = NULL, &$parame
 	 * Parses a timestamp
 	 *
 	 * @link http://de3.php.net/manual/en/datetime.formats.php
-	 * @todo add millisecond resolution
 	 *
 	 * @param mixed $string int, float or string to parse
-	 * @param float $now in ms since 1970
 	 * @return float
+	 * @throws \Exception
 	 */
 	public static function parseDateTimeString($string) {
 		if (ctype_digit((string)$string)) { // handling as ms timestamp