Merge remote-tracking branch 'upstream/dev' into dev

4 files changed, 294 insertions, 95 deletions

diff --git a/app/Controllers/configureController.php b/app/Controllers/configureController.php
index b1cd45014..231865bd7 100755
--- a/app/Controllers/configureController.php
+++ b/app/Controllers/configureController.php
@@ -1,11 +1,22 @@
 <?php
 
+/**
+ * Controller to handle every configuration options.
+ */
 class FreshRSS_configure_Controller extends Minz_ActionController {
+	/**
+	 * This action is called before every other action in that class. It is
+	 * the common boiler plate for every action. It is triggered by the
+	 * underlying framework.
+	 *
+	 * @todo see if the category default configuration is needed here or if
+	 *       we can move it to the categorize action
+	 */
 	public function firstAction() {
 		if (!$this->view->loginOk) {
 			Minz_Error::error(
 				403,
-				array('error' => array(Minz_Translate::t('access_denied')))
+				array('error' => array(_t('access_denied')))
 			);
 		}
 
@@ -13,6 +24,18 @@ class FreshRSS_configure_Controller extends Minz_ActionController {
 		$catDAO->checkDefault();
 	}
 
+	/**
+	 * This action handles the category configuration page
+	 *
+	 * It displays the category configuration page.
+	 * If this action is reached through a POST request, it loops through
+	 * every category to check for modification then add a new category if
+	 * needed then sends a notification to the user.
+	 * If a category name is emptied, the category is deleted and all
+	 * related feeds are moved to the default category. Related user queries
+	 * are deleted too.
+	 * If a category name is changed, it is updated.
+	 */
 	public function categorizeAction() {
 		$feedDAO = FreshRSS_Factory::createFeedDao();
 		$catDAO = new FreshRSS_CategoryDAO();
@@ -34,6 +57,10 @@ class FreshRSS_configure_Controller extends Minz_ActionController {
 				} elseif ($ids[$key] != $defaultId) {
 					$feedDAO->changeCategory($ids[$key], $defaultId);
 					$catDAO->deleteCategory($ids[$key]);
+
+					// Remove related queries.
+					$this->view->conf->remove_query_by_get('c_' . $ids[$key]);
+					$this->view->conf->save();
 				}
 			}
 
@@ -50,22 +77,37 @@ class FreshRSS_configure_Controller extends Minz_ActionController {
 			}
 			invalidateHttpCache();
 
-			$notif = array(
-				'type' => 'good',
-				'content' => Minz_Translate::t('categories_updated')
-			);
-			Minz_Session::_param('notification', $notif);
-
-			Minz_Request::forward(array('c' => 'configure', 'a' => 'categorize'), true);
+			Minz_Request::good(_t('categories_updated'),
+			                   array('c' => 'configure', 'a' => 'categorize'));
 		}
 
 		$this->view->categories = $catDAO->listCategories(false);
 		$this->view->defaultCategory = $catDAO->getDefault();
 		$this->view->feeds = $feedDAO->listFeeds();
 
-		Minz_View::prependTitle(Minz_Translate::t('categories_management') . ' · ');
+		Minz_View::prependTitle(_t('categories_management') . ' · ');
 	}
 
+	/**
+	 * This action handles the feed configuration page.
+	 *
+	 * It displays the feed configuration page.
+	 * If this action is reached through a POST request, it stores all new
+	 * configuraiton values then sends a notification to the user.
+	 *
+	 * The options available on the page are:
+	 *   - name
+	 *   - description
+	 *   - website URL
+	 *   - feed URL
+	 *   - category id (default: default category id)
+	 *   - CSS path to article on website
+	 *   - display in main stream (default: 0)
+	 *   - HTTP authentication
+	 *   - number of article to retain (default: -2)
+	 *   - refresh frequency (default: -2)
+	 * Default values are empty strings unless specified.
+	 */
 	public function feedAction() {
 		$catDAO = new FreshRSS_CategoryDAO();
 		$this->view->categories = $catDAO->listCategories(false);
@@ -85,7 +127,7 @@ class FreshRSS_configure_Controller extends Minz_ActionController {
 			if (!$this->view->flux) {
 				Minz_Error::error(
 					404,
-					array('error' => array(Minz_Translate::t('page_not_found')))
+					array('error' => array(_t('page_not_found')))
 				);
 			} else {
 				if (Minz_Request::isPost() && $this->view->flux) {
@@ -117,12 +159,12 @@ class FreshRSS_configure_Controller extends Minz_ActionController {
 						$this->view->flux->faviconPrepare();
 						$notif = array(
 							'type' => 'good',
-							'content' => Minz_Translate::t('feed_updated')
+							'content' => _t('feed_updated')
 						);
 					} else {
 						$notif = array(
 							'type' => 'bad',
-							'content' => Minz_Translate::t('error_occurred_update')
+							'content' => _t('error_occurred_update')
 						);
 					}
 					invalidateHttpCache();
@@ -131,21 +173,41 @@ class FreshRSS_configure_Controller extends Minz_ActionController {
 					Minz_Request::forward(array('c' => 'configure', 'a' => 'feed', 'params' => array('id' => $id)), true);
 				}
 
-				Minz_View::prependTitle(Minz_Translate::t('rss_feed_management') . ' — ' . $this->view->flux->name() . ' · ');
+				Minz_View::prependTitle(_t('rss_feed_management') . ' — ' . $this->view->flux->name() . ' · ');
 			}
 		} else {
-			Minz_View::prependTitle(Minz_Translate::t('rss_feed_management') . ' · ');
+			Minz_View::prependTitle(_t('rss_feed_management') . ' · ');
 		}
 	}
 
+	/**
+	 * This action handles the display configuration page.
+	 *
+	 * It displays the display configuration page.
+	 * If this action is reached through a POST request, it stores all new
+	 * configuration values then sends a notification to the user.
+	 *
+	 * The options available on the page are:
+	 *   - language (default: en)
+	 *   - theme (default: Origin)
+	 *   - content width (default: thin)
+	 *   - display of read action in header
+	 *   - display of favorite action in header
+	 *   - display of date in header
+	 *   - display of open action in header
+	 *   - display of read action in footer
+	 *   - display of favorite action in footer
+	 *   - display of sharing action in footer
+	 *   - display of tags in footer
+	 *   - display of date in footer
+	 *   - display of open action in footer
+	 *   - html5 notification timeout (default: 0)
+	 * Default values are false unless specified.
+	 */
 	public function displayAction() {
 		if (Minz_Request::isPost()) {
 			$this->view->conf->_language(Minz_Request::param('language', 'en'));
-			$themeId = Minz_Request::param('theme', '');
-			if ($themeId == '') {
-				$themeId = FreshRSS_Themes::defaultTheme;
-			}
-			$this->view->conf->_theme($themeId);
+			$this->view->conf->_theme(Minz_Request::param('theme', FreshRSS_Themes::$defaultTheme));
 			$this->view->conf->_content_width(Minz_Request::param('content_width', 'thin'));
 			$this->view->conf->_topline_read(Minz_Request::param('topline_read', false));
 			$this->view->conf->_topline_favorite(Minz_Request::param('topline_favorite', false));
@@ -164,20 +226,42 @@ class FreshRSS_configure_Controller extends Minz_ActionController {
 			Minz_Translate::reset();
 			invalidateHttpCache();
 
-			$notif = array(
-				'type' => 'good',
-				'content' => Minz_Translate::t('configuration_updated')
-			);
-			Minz_Session::_param('notification', $notif);
-
-			Minz_Request::forward(array('c' => 'configure', 'a' => 'display'), true);
+			Minz_Request::good(_t('configuration_updated'),
+			                   array('c' => 'configure', 'a' => 'display'));
 		}
 
 		$this->view->themes = FreshRSS_Themes::get();
 
-		Minz_View::prependTitle(Minz_Translate::t('display_configuration') . ' · ');
+		Minz_View::prependTitle(_t('display_configuration') . ' · ');
 	}
 
+	/**
+	 * This action handles the reading configuration page.
+	 *
+	 * It displays the reading configuration page.
+	 * If this action is reached through a POST request, it stores all new
+	 * configuration values then sends a notification to the user.
+	 *
+	 * The options available on the page are:
+	 *   - number of posts per page (default: 10)
+	 *   - view mode (default: normal)
+	 *   - default article view (default: all)
+	 *   - load automatically articles
+	 *   - display expanded articles
+	 *   - display expanded categories
+	 *   - hide categories and feeds without unread articles
+	 *   - jump on next category or feed when marked as read
+	 *   - image lazy loading
+	 *   - stick open articles to the top
+	 *   - display a confirmation when reading all articles
+	 *   - article order (default: DESC)
+	 *   - mark articles as read when:
+	 *       - displayed
+	 *       - opened on site
+	 *       - scrolled
+	 *       - received
+	 * Default values are false unless specified.
+	 */
 	public function readingAction() {
 		if (Minz_Request::isPost()) {
 			$this->view->conf->_posts_per_page(Minz_Request::param('posts_per_page', 10));
@@ -204,18 +288,20 @@ class FreshRSS_configure_Controller extends Minz_ActionController {
 			Minz_Translate::reset();
 			invalidateHttpCache();
 
-			$notif = array(
-				'type' => 'good',
-				'content' => Minz_Translate::t('configuration_updated')
-			);
-			Minz_Session::_param('notification', $notif);
-
-			Minz_Request::forward(array('c' => 'configure', 'a' => 'reading'), true);
+			Minz_Request::good(_t('configuration_updated'),
+			                   array('c' => 'configure', 'a' => 'reading'));
 		}
 
-		Minz_View::prependTitle(Minz_Translate::t('reading_configuration') . ' · ');
+		Minz_View::prependTitle(_t('reading_configuration') . ' · ');
 	}
 
+	/**
+	 * This action handles the sharing configuration page.
+	 *
+	 * It displays the sharing configuration page.
+	 * If this action is reached through a POST request, it stores all
+	 * configuration values then sends a notification to the user.
+	 */
 	public function sharingAction() {
 		if (Minz_Request::isPost()) {
 			$params = Minz_Request::params();
@@ -223,25 +309,31 @@ class FreshRSS_configure_Controller extends Minz_ActionController {
 			$this->view->conf->save();
 			invalidateHttpCache();
 
-			$notif = array(
-				'type' => 'good',
-				'content' => Minz_Translate::t('configuration_updated')
-			);
-			Minz_Session::_param('notification', $notif);
-
-			Minz_Request::forward(array('c' => 'configure', 'a' => 'sharing'), true);
+			Minz_Request::good(_t('configuration_updated'),
+			                   array('c' => 'configure', 'a' => 'sharing'));
 		}
 
-		Minz_View::prependTitle(Minz_Translate::t('sharing') . ' · ');
+		Minz_View::prependTitle(_t('sharing') . ' · ');
 	}
 
+	/**
+	 * This action handles the shortcut configuration page.
+	 *
+	 * It displays the shortcut configuration page.
+	 * If this action is reached through a POST request, it stores all new
+	 * configuration values then sends a notification to the user.
+	 *
+	 * The authorized values for shortcuts are letters (a to z), numbers (0
+	 * to 9), function keys (f1 to f12), backspace, delete, down, end, enter,
+	 * escape, home, insert, left, page down, page up, return, right, space,
+	 * tab and up.
+	 */
 	public function shortcutAction() {
 		$list_keys = array('a', 'b', 'backspace', 'c', 'd', 'delete', 'down', 'e', 'end', 'enter',
 		                    'escape', 'f', 'g', 'h', 'home', 'i', 'insert', 'j', 'k', 'l', 'left',
 		                    'm', 'n', 'o', 'p', 'page_down', 'page_up', 'q', 'r', 'return', 'right',
 		                    's', 'space', 't', 'tab', 'u', 'up', 'v', 'w', 'x', 'y',
-		                    'z', '0', '1', '2', '3', '4', '5', '6', '7', '8',
-		                    '9', 'f1', 'f2', 'f3', 'f4', 'f5', 'f6', 'f7', 'f8', 'f9',
+		                    'z', 'f1', 'f2', 'f3', 'f4', 'f5', 'f6', 'f7', 'f8', 'f9',
 		                    'f10', 'f11', 'f12');
 		$this->view->list_keys = $list_keys;
 
@@ -259,44 +351,50 @@ class FreshRSS_configure_Controller extends Minz_ActionController {
 			$this->view->conf->save();
 			invalidateHttpCache();
 
-			$notif = array(
-				'type' => 'good',
-				'content' => Minz_Translate::t('shortcuts_updated')
-			);
-			Minz_Session::_param('notification', $notif);
-
-			Minz_Request::forward(array('c' => 'configure', 'a' => 'shortcut'), true);
+			Minz_Request::good(_t('shortcuts_updated'),
+			                   array('c' => 'configure', 'a' => 'shortcut'));
 		}
 
-		Minz_View::prependTitle(Minz_Translate::t('shortcuts') . ' · ');
+		Minz_View::prependTitle(_t('shortcuts') . ' · ');
 	}
 
+	/**
+	 * This action display the user configuration page
+	 *
+	 * @todo move that action in the user controller
+	 */
 	public function usersAction() {
-		Minz_View::prependTitle(Minz_Translate::t('users') . ' · ');
+		Minz_View::prependTitle(_t('users') . ' · ');
 	}
 
+	/**
+	 * This action handles the archive configuration page.
+	 *
+	 * It displays the archive configuration page.
+	 * If this action is reached through a POST request, it stores all new
+	 * configuration values then sends a notification to the user.
+	 *
+	 * The options available on that page are:
+	 *   - duration to retain old article (default: 3)
+	 *   - number of article to retain per feed (default: 0)
+	 *   - refresh frequency (default: -2)
+	 *
+	 * @todo explain why the default value is -2 but this value does not
+	 *       exist in the drop-down list
+	 */
 	public function archivingAction() {
 		if (Minz_Request::isPost()) {
-			$old = Minz_Request::param('old_entries', 3);
-			$keepHistoryDefault = Minz_Request::param('keep_history_default', 0);
-			$ttlDefault = Minz_Request::param('ttl_default', -2);
-
-			$this->view->conf->_old_entries($old);
-			$this->view->conf->_keep_history_default($keepHistoryDefault);
-			$this->view->conf->_ttl_default($ttlDefault);
+			$this->view->conf->_old_entries(Minz_Request::param('old_entries', 3));
+			$this->view->conf->_keep_history_default(Minz_Request::param('keep_history_default', 0));
+			$this->view->conf->_ttl_default(Minz_Request::param('ttl_default', -2));
 			$this->view->conf->save();
 			invalidateHttpCache();
 
-			$notif = array(
-				'type' => 'good',
-				'content' => Minz_Translate::t('configuration_updated')
-			);
-			Minz_Session::_param('notification', $notif);
-
-			Minz_Request::forward(array('c' => 'configure', 'a' => 'archiving'), true);
+			Minz_Request::good(_t('configuration_updated'),
+			                   array('c' => 'configure', 'a' => 'archiving'));
 		}
 
-		Minz_View::prependTitle(Minz_Translate::t('archiving_configuration') . ' · ');
+		Minz_View::prependTitle(_t('archiving_configuration') . ' · ');
 
 		$entryDAO = FreshRSS_Factory::createEntryDao();
 		$this->view->nb_total = $entryDAO->count();
@@ -306,28 +404,35 @@ class FreshRSS_configure_Controller extends Minz_ActionController {
 			$this->view->size_total = $entryDAO->size(true);
 		}
 	}
-	
+
+	/**
+	 * This action handles the user queries configuration page.
+	 *
+	 * If this action is reached through a POST request, it stores all new
+	 * configuration values then sends a notification to the user then
+	 * redirect to the same page.
+	 * If this action is not reached through a POST request, it displays the
+	 * configuration page and verifies that every user query is runable by
+	 * checking if categories and feeds are still in use.
+	 */
 	public function queriesAction() {
 		if (Minz_Request::isPost()) {
 			$queries = Minz_Request::param('queries', array());
 
 			foreach ($queries as $key => $query) {
 				if (!$query['name']) {
-					$query['name'] = Minz_Translate::t('query_number', $key + 1);
+					$query['name'] = _t('query_number', $key + 1);
 				}
 			}
 			$this->view->conf->_queries($queries);
 			$this->view->conf->save();
 
-			$notif = array(
-				'type' => 'good',
-				'content' => Minz_Translate::t('configuration_updated')
-			);
-			Minz_Session::_param('notification', $notif);
-
-			Minz_Request::forward(array('c' => 'configure', 'a' => 'queries'), true);
+			Minz_Request::good(_t('configuration_updated'),
+			                   array('c' => 'configure', 'a' => 'queries'));
 		} else {
 			$this->view->query_get = array();
+			$cat_dao = new FreshRSS_CategoryDAO();
+			$feed_dao = FreshRSS_Factory::createFeedDao();
 			foreach ($this->view->conf->queries as $key => $query) {
 				if (!isset($query['get'])) {
 					continue;
@@ -335,51 +440,83 @@ class FreshRSS_configure_Controller extends Minz_ActionController {
 
 				switch ($query['get'][0]) {
 				case 'c':
-					$dao = new FreshRSS_CategoryDAO();
-					$category = $dao->searchById(substr($query['get'], 2));
+					$category = $cat_dao->searchById(substr($query['get'], 2));
+
+					$deprecated = true;
+					$cat_name = '';
+					if ($category) {
+						$cat_name = $category->name();
+						$deprecated = false;
+					}
+
 					$this->view->query_get[$key] = array(
 						'type' => 'category',
-						'name' => $category->name(),
+						'name' => $cat_name,
+						'deprecated' => $deprecated,
 					);
 					break;
 				case 'f':
-					$dao = FreshRSS_Factory::createFeedDao();
-					$feed = $dao->searchById(substr($query['get'], 2));
+					$feed = $feed_dao->searchById(substr($query['get'], 2));
+
+					$deprecated = true;
+					$feed_name = '';
+					if ($feed) {
+						$feed_name = $feed->name();
+						$deprecated = false;
+					}
+
 					$this->view->query_get[$key] = array(
 						'type' => 'feed',
-						'name' => $feed->name(),
+						'name' => $feed_name,
+						'deprecated' => $deprecated,
 					);
 					break;
 				case 's':
 					$this->view->query_get[$key] = array(
 						'type' => 'favorite',
 						'name' => 'favorite',
+						'deprecated' => false,
 					);
 					break;
 				case 'a':
 					$this->view->query_get[$key] = array(
 						'type' => 'all',
 						'name' => 'all',
+						'deprecated' => false,
 					);
 					break;
 				}
 			}
 		}
 
-		Minz_View::prependTitle(Minz_Translate::t('queries') . ' · ');
+		Minz_View::prependTitle(_t('queries') . ' · ');
 	}
-	
+
+	/**
+	 * This action handles the creation of a user query.
+	 *
+	 * It gets the GET parameters and stores them in the configuration query
+	 * storage. Before it is saved, the unwanted parameters are unset to keep
+	 * lean data.
+	 */
 	public function addQueryAction() {
+		$whitelist = array('get', 'order', 'name', 'search', 'state');
 		$queries = $this->view->conf->queries;
 		$query = Minz_Request::params();
-		$query['name'] = Minz_Translate::t('query_number', count($queries) + 1);
-		unset($query['output']);
-		unset($query['token']);
+		$query['name'] = _t('query_number', count($queries) + 1);
+		foreach ($query as $key => $value) {
+			if (!in_array($key, $whitelist)) {
+				unset($query[$key]);
+			}
+		}
+		if (!empty($query['state']) && $query['state'] & FreshRSS_Entry::STATE_STRICT) {
+			$query['state'] -= FreshRSS_Entry::STATE_STRICT;
+		}
 		$queries[] = $query;
 		$this->view->conf->_queries($queries);
 		$this->view->conf->save();
 
-		// Minz_Request::forward(array('params' => $query), true);
-		Minz_Request::forward(array('c' => 'configure', 'a' => 'queries'), true);
+		Minz_Request::good(_t('query_created', $query['name']),
+		                   array('c' => 'configure', 'a' => 'queries'));
 	}
 }
diff --git a/app/Controllers/feedController.php b/app/Controllers/feedController.php
index 3326b2059..c7cc25fbb 100755
--- a/app/Controllers/feedController.php
+++ b/app/Controllers/feedController.php
@@ -383,7 +383,16 @@ class FreshRSS_feed_Controller extends Minz_ActionController {
 
 			$feedDAO = FreshRSS_Factory::createFeedDao();
 			if ($type == 'category') {
+				// List feeds to remove then related user queries.
+				$feeds = $feedDAO->listByCategory($id);
+
 				if ($feedDAO->deleteFeedByCategory ($id)) {
+					// Remove related queries
+					foreach ($feeds as $feed) {
+						$this->view->conf->remove_query_by_get('f_' . $feed->id());
+					}
+					$this->view->conf->save();
+
 					$notif = array (
 						'type' => 'good',
 						'content' => Minz_Translate::t ('category_emptied')
@@ -397,6 +406,10 @@ class FreshRSS_feed_Controller extends Minz_ActionController {
 				}
 			} else {
 				if ($feedDAO->deleteFeed ($id)) {
+					// Remove related queries
+					$this->view->conf->remove_query_by_get('f_' . $id);
+					$this->view->conf->save();
+
 					$notif = array (
 						'type' => 'good',
 						'content' => Minz_Translate::t ('feed_deleted')
@@ -412,10 +425,13 @@ class FreshRSS_feed_Controller extends Minz_ActionController {
 
 			Minz_Session::_param ('notification', $notif);
 
-			if ($type == 'category') {
-				Minz_Request::forward (array ('c' => 'configure', 'a' => 'categorize'), true);
+			$redirect_url = Minz_Request::param('r', false, true);
+			if ($redirect_url) {
+				Minz_Request::forward($redirect_url);
+			} elseif ($type == 'category') {
+				Minz_Request::forward(array ('c' => 'configure', 'a' => 'categorize'), true);
 			} else {
-				Minz_Request::forward (array ('c' => 'configure', 'a' => 'feed'), true);
+				Minz_Request::forward(array ('c' => 'configure', 'a' => 'feed'), true);
 			}
 		}
 	}
diff --git a/app/Controllers/indexController.php b/app/Controllers/indexController.php
index b69c09127..e8e26b142 100755
--- a/app/Controllers/indexController.php
+++ b/app/Controllers/indexController.php
@@ -84,7 +84,7 @@ class FreshRSS_index_Controller extends Minz_ActionController {
 		$first = Minz_Request::param ('next', '');
 
 		$ajax_request = Minz_Request::param('ajax', false);
-		if ($ajax_request == 1 && $this->view->conf->display_posts) {
+		if ($output === 'reader') {
 			$nb = max(1, round($nb / 2));
 		}
 
@@ -337,6 +337,10 @@ class FreshRSS_index_Controller extends Minz_ActionController {
 	}
 
 	public function formLoginAction () {
+		if ($this->view->loginOk) {
+			Minz_Request::forward(array('c' => 'index', 'a' => 'index'), true);
+		}
+
 		if (Minz_Request::isPost()) {
 			$ok = false;
 			$nonce = Minz_Session::param('nonce');
diff --git a/app/Controllers/statsController.php b/app/Controllers/statsController.php
index 000b41dd2..256543f37 100644
--- a/app/Controllers/statsController.php
+++ b/app/Controllers/statsController.php
@@ -1,7 +1,21 @@
 <?php
 
+/**
+ * Controller to handle application statistics.
+ */
 class FreshRSS_stats_Controller extends Minz_ActionController {
 
+	/**
+	 * This action handles the statistic main page.
+	 *
+	 * It displays the statistic main page.
+	 * The values computed to display the page are:
+	 *   - repartition of read/unread/favorite/not favorite
+	 *   - number of article per day
+	 *   - number of feed by category
+	 *   - number of article by category
+	 *   - list of most prolific feed
+	 */
 	public function indexAction() {
 		$statsDAO = FreshRSS_Factory::createStatsDAO();
 		Minz_View::appendScript(Minz_Url::display('/scripts/flotr2.min.js?' . @filemtime(PUBLIC_PATH . '/scripts/flotr2.min.js')));
@@ -12,6 +26,17 @@ class FreshRSS_stats_Controller extends Minz_ActionController {
 		$this->view->topFeed = $statsDAO->calculateTopFeed();
 	}
 
+	/**
+	 * This action handles the idle feed statistic page.
+	 *
+	 * It displays the list of idle feed for different period. The supported
+	 * periods are:
+	 *   - last year
+	 *   - last 6 months
+	 *   - last 3 months
+	 *   - last month
+	 *   - last week
+	 */
 	public function idleAction() {
 		$statsDAO = FreshRSS_Factory::createStatsDAO();
 		$feeds = $statsDAO->calculateFeedLastDate();
@@ -56,6 +81,18 @@ class FreshRSS_stats_Controller extends Minz_ActionController {
 		$this->view->idleFeeds = $idleFeeds;
 	}
 
+	/**
+	 * This action handles the article repartition statistic page.
+	 *
+	 * It displays the number of article and the average of article for the
+	 * following periods:
+	 *   - hour of the day
+	 *   - day of the week
+	 *   - month
+	 *
+	 * @todo verify that the metrics used here make some sense. Especially
+	 *       for the average.
+	 */
 	public function repartitionAction() {
 		$statsDAO = FreshRSS_Factory::createStatsDAO();
 		$categoryDAO = new FreshRSS_CategoryDAO();
@@ -74,6 +111,11 @@ class FreshRSS_stats_Controller extends Minz_ActionController {
 		$this->view->averageMonth = $statsDAO->calculateEntryAveragePerFeedPerMonth($id);
 	}
 
+	/**
+	 * This action is called before every other action in that class. It is
+	 * the common boiler plate for every action. It is triggered by the
+	 * underlying framework.
+	 */
 	public function firstAction() {
 		if (!$this->view->loginOk) {
 			Minz_Error::error(