Add comments to Context object.

See https://github.com/marienfressinaud/FreshRSS/issues/634

app/Controllers/indexController.php

@@ -137,6 +137,13 @@ class FreshRSS_index_Controller extends Minz_ActionController {
 	 *   - next (default: empty string)
 	 */
 	private function updateContext() {
+		// Update number of read / unread variables.
+		$entryDAO = FreshRSS_Factory::createEntryDao();
+		FreshRSS_Context::$total_starred = $entryDAO->countUnreadReadFavorites();
+		FreshRSS_Context::$total_unread = FreshRSS_CategoryDAO::CountUnreads(
+			FreshRSS_Context::$categories, 1
+		);
+
 		FreshRSS_Context::_get(Minz_Request::param('get', 'a'));
 
 		FreshRSS_Context::$state = Minz_Request::param(

app/Models/Context.php

@@ -34,6 +34,11 @@ class FreshRSS_Context {
 	public static $next_id = '';
 	public static $id_max = '';
 
+	/**
+	 * Initialize the context.
+	 *
+	 * Set the correct $conf and $categories variables.
+	 */
 	public static function init() {
 		// Init configuration.
 		$current_user = Minz_Session::param('currentUser');
@@ -45,19 +50,19 @@ class FreshRSS_Context {
 		}
 
 		$catDAO = new FreshRSS_CategoryDAO();
-		$entryDAO = FreshRSS_Factory::createEntryDao();
-
 		self::$categories = $catDAO->listCategories();
-
-		// Update number of read / unread variables.
-		self::$total_starred = $entryDAO->countUnreadReadFavorites();
-		self::$total_unread = FreshRSS_CategoryDAO::CountUnreads(self::$categories, 1);
 	}
 
+	/**
+	 * Returns if the current state includes $state parameter.
+	 */
 	public static function isStateEnabled($state) {
 		return self::$state & $state;
 	}
 
+	/**
+	 * Returns the current state with or without $state parameter.
+	 */
 	public static function getRevertState($state) {
 		if (self::$state & $state) {
 			return self::$state & ~$state;
@@ -66,6 +71,65 @@ class FreshRSS_Context {
 		}
 	}
 
+	/**
+	 * Return the current get as a string or an array.
+	 *
+	 * If $array is true, the first item of the returned value is 'f' or 'c' and
+	 * the second is the id.
+	 */
+	public static function currentGet($array = false) {
+		if (self::$current_get['all']) {
+			return 'a';
+		} elseif (self::$current_get['starred']) {
+			return 's';
+		} elseif (self::$current_get['feed']) {
+			if ($array) {
+				return array('f', self::$current_get['feed']);
+			} else {
+				return 'f_' . self::$current_get['feed'];
+			}
+		} elseif (self::$current_get['category']) {
+			if ($array) {
+				return array('c', self::$current_get['category']);
+			} else {
+				return 'c_' . self::$current_get['category'];
+			}
+		}
+	}
+
+	/**
+	 * Return true if $get parameter correspond to the $current_get attribute.
+	 */
+	public static function isCurrentGet($get) {
+		$type = $get[0];
+		$id = substr($get, 2);
+
+		switch($type) {
+		case 'a':
+			return self::$current_get['all'];
+		case 's':
+			return self::$current_get['starred'];
+		case 'f':
+			return self::$current_get['feed'] == $id;
+		case 'c':
+			return self::$current_get['category'] == $id;
+		default:
+			return false;
+		}
+	}
+
+	/**
+	 * Set the current $get attribute.
+	 *
+	 * Valid $get parameter are:
+	 *   - a
+	 *   - s
+	 *   - f_<feed id>
+	 *   - c_<category id>
+	 *
+	 * $name and $get_unread attributes are also updated as $next_get
+	 * Raise an exception if id or $get is invalid.
+	 */
 	public static function _get($get) {
 		$type = $get[0];
 		$id = substr($get, 2);
@@ -86,6 +150,7 @@ class FreshRSS_Context {
 			self::$state = self::$state | FreshRSS_Entry::STATE_FAVORITE;
 			break;
 		case 'f':
+			// We try to find the corresponding feed.
 			$feed = FreshRSS_CategoryDAO::findFeed(self::$categories, $id);
 			if ($feed === null) {
 				$feedDAO = FreshRSS_Factory::createFeedDao();
@@ -102,6 +167,7 @@ class FreshRSS_Context {
 			self::$get_unread = $feed->nbNotRead();
 			break;
 		case 'c':
+			// We try to find the corresponding category.
 			self::$current_get['category'] = $id;
 			if (!isset(self::$categories[$id])) {
 				$catDAO = new FreshRSS_CategoryDAO();
@@ -124,46 +190,12 @@ class FreshRSS_Context {
 		self::_nextGet();
 	}
 
-	public static function currentGet($array = false) {
-		if (self::$current_get['all']) {
-			return 'a';
-		} elseif (self::$current_get['starred']) {
-			return 's';
-		} elseif (self::$current_get['feed']) {
-			if ($array) {
-				return array('f', self::$current_get['feed']);
-			} else {
-				return 'f_' . self::$current_get['feed'];
-			}
-		} elseif (self::$current_get['category']) {
-			if ($array) {
-				return array('c', self::$current_get['category']);
-			} else {
-				return 'c_' . self::$current_get['category'];
-			}
-		}
-	}
-
-	public static function isCurrentGet($get) {
-		$type = $get[0];
-		$id = substr($get, 2);
-
-		switch($type) {
-		case 'a':
-			return self::$current_get['all'];
-		case 's':
-			return self::$current_get['starred'];
-		case 'f':
-			return self::$current_get['feed'] == $id;
-		case 'c':
-			return self::$current_get['category'] == $id;
-		default:
-			return false;
-		}
-	}
-
+	/**
+	 * Set the value of $next_get attribute.
+	 */
 	public static function _nextGet() {
 		$get = self::currentGet();
+		// By default, $next_get == $get
 		self::$next_get = $get;
 
 		if (self::$conf->onread_jump_next && strlen($get) > 2) {
@@ -171,13 +203,18 @@ class FreshRSS_Context {
 			$found_current_get = false;
 			switch ($get[0]) {
 			case 'f':
+				// We search the next feed with at least one unread article in
+				// same category as the currend feed.
 				foreach (self::$categories as $cat) {
 					if ($cat->id() != self::$current_get['category']) {
+						// We look into the category of the current feed!
 						continue;
 					}
 
 					foreach ($cat->feeds() as $feed) {
 						if ($feed->id() == self::$current_get['feed']) {
+							// Here is our current feed! Fine, the next one will
+							// be a potential candidate.
 							$found_current_get = true;
 							continue;
 						}
@@ -185,6 +222,9 @@ class FreshRSS_Context {
 						if ($feed->nbNotRead() > 0) {
 							$another_unread_id = $feed->id();
 							if ($found_current_get) {
+								// We have found our current feed and now we
+								// have an feed with unread articles. Leave the
+								// loop!
 								break;
 							}
 						}
@@ -192,13 +232,17 @@ class FreshRSS_Context {
 					break;
 				}
 
+				// If no feed have been found, next_get is the current category.
 				self::$next_get = empty($another_unread_id) ?
 				                  'c_' . self::$current_get['category'] :
 				                  'f_' . $another_unread_id;
 				break;
 			case 'c':
+				// We search the next category with at least one unread article.
 				foreach (self::$categories as $cat) {
 					if ($cat->id() == self::$current_get['category']) {
+						// Here is our current category! Next one could be our
+						// champion if it has unread articles.
 						$found_current_get = true;
 						continue;
 					}
@@ -206,11 +250,14 @@ class FreshRSS_Context {
 					if ($cat->nbNotRead() > 0) {
 						$another_unread_id = $cat->id();
 						if ($found_current_get) {
+							// Unread articles and the current category has
+							// already been found? Leave the loop!
 							break;
 						}
 					}
 				}
 
+				// No unread category? The main stream will be our destination!
 				self::$next_get = empty($another_unread_id) ?
 				                  'a' :
 				                  'c_' . $another_unread_id;