From 0420a989391c9af30ee6d85638c81bfb4f605132 Mon Sep 17 00:00:00 2001
From: Alexis Degrugillier <github@ainw.org>
Date: Sun, 21 Sep 2014 11:51:53 -0400
Subject: Add comments on the stat controller

---
 app/Controllers/statsController.php | 42 +++++++++++++++++++++++++++++++++++++
 1 file changed, 42 insertions(+)

diff --git a/app/Controllers/statsController.php b/app/Controllers/statsController.php
index 000b41dd2..64f66f2fa 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(
-- 
cgit v1.2.3