Write class documentation

library/Icinga/Protocol/File/Query.php

@@ -10,26 +10,53 @@ class Query extends BaseQuery
 
     private $filters = array();
 
+    /**
+     * Nothing to do here
+     */
     public function applyFilter()
-    {}// ?
+    {}
 
+    /**
+     * Sort query result chronological
+     *
+     * @param string $dir  Sort direction, 'ASC' or 'DESC' (default)
+     *
+     * @return Query
+     */
     public function order($dir)
     {
         $this->sortDir = ($dir === null || strtoupper(trim($dir)) === 'DESC') ? self::SORT_DESC : self::SORT_ASC;
         return $this;
     }
 
+    /**
+     * Return true if sorting descending, false otherwise
+     *
+     * @return bool
+     */
     public function sortDesc()
     {
         return $this->sortDir === self::SORT_DESC;
     }
 
-    public function where($expression)
+    /**
+     * Add an mandatory filter expression to be applied on this query
+     *
+     * @param string $expression  the filter expression to be applied
+     *
+     * @return Query
+     */
+    public function andWhere($expression)
     {
         $this->filters[] = $expression;
         return $this;
     }
 
+    /**
+     * Get filters currently applied on this query
+     *
+     * @return array
+     */
     public function getFilters()
     {
         return $this->filters;

library/Icinga/Protocol/File/Reader.php

@@ -16,11 +16,21 @@ class Reader implements DatasourceInterface
         $this->filename = $config->filename;
     }
 
+    /**
+     * Instantiate a Query object
+     *
+     * @return Query
+     */
     public function select()
     {
         return new Query($this);
     }
 
+    /**
+     * Fetch result as an array of objects
+     *
+     * @return array
+     */
     public function fetchAll(Query $query)
     {
         $all = array();
@@ -33,6 +43,11 @@ class Reader implements DatasourceInterface
         return $all;
     }
 
+    /**
+     * Fetch first result row
+     *
+     * @return object
+     */
     public function fetchRow(Query $query)
     {
         $all = $this->fetchAll($query);
@@ -42,6 +57,11 @@ class Reader implements DatasourceInterface
         return null;
     }
 
+    /**
+     * Fetch first result column
+     *
+     * @return array
+     */
     public function fetchColumn(Query $query)
     {
         $column = array();
@@ -54,6 +74,11 @@ class Reader implements DatasourceInterface
         return $column;
     }
 
+    /**
+     * Fetch first column value from first result row
+     *
+     * @return mixed
+     */
     public function fetchOne(Query $query)
     {
         $pairs = $this->fetchPairs($query);
@@ -65,11 +90,30 @@ class Reader implements DatasourceInterface
         return null;
     }
 
+    /**
+     * Fetch result as a key/value pair array
+     *
+     * @return array
+     */
     public function fetchPairs(Query $query)
     {
         return $this->read($query);
     }
 
+    /**
+     * If given $line matches the $query's PCRE pattern and contains all the strings in the $query's filters array,
+     * return an associative array of the matches of the PCRE pattern.
+     * Otherwise, return false.
+     * If preg_match returns false, it failed parsing the PCRE pattern.
+     * In that case, throw an exception.
+     *
+     * @param string $line
+     * @param Query $query
+     *
+     * @return array|bool
+     *
+     * @throws \Exception
+     */
     public function validateLine($line, Query $query)
     {
         $data = array();
@@ -92,6 +136,13 @@ class Reader implements DatasourceInterface
         return false;
     }
 
+    /**
+     * Skip and read as many lines as needed according to given $query.
+     *
+     * @param Query $query
+     *
+     * @return array  result
+     */
     public function read(Query $query)
     {
         $skip_lines = $query->getOffset();
@@ -99,13 +150,13 @@ class Reader implements DatasourceInterface
         if ($skip_lines === null) {
             $skip_lines = 0;
         }
-        if ($query->sortDesc()) {
+        return $this->{$query->sortDesc() ? 'readFromEnd' : 'readFromStart'}($skip_lines, $read_lines, $query);
-            return $this->readFromEnd($skip_lines, $read_lines, $query);
-        }
-        return $this->readFromStart($skip_lines, $read_lines, $query);
     }
 
-    public function readFromEnd($skip_lines = null, $read_lines = null, Query $query)
+    /**
+     * Backend for $this->read
+     */
+    public function readFromEnd($skip_lines, $read_lines, Query $query)
     {
         $PHP_EOL_len = strlen(PHP_EOL);
         $lines = array();
@@ -139,7 +190,10 @@ class Reader implements DatasourceInterface
         return $lines;
     }
 
-    public function readFromStart($skip_lines = null, $read_lines = null, Query $query)
+    /**
+     * Backend for $this->read
+     */
+    public function readFromStart($skip_lines, $read_lines, Query $query)
     {
         $PHP_EOL_len = strlen(PHP_EOL);
         $lines = array();
@@ -170,6 +224,13 @@ class Reader implements DatasourceInterface
         return $lines;
     }
 
+    /**
+     * Return the number of available valid lines.
+     *
+     * @param Query $query
+     *
+     * @return int
+     */
     public function count(Query $query) {
         $PHP_EOL_len = strlen(PHP_EOL);
         $lines = 0;