From ea7f21ba7f4049b51c2978b7ebaad00e17fa5af5 Mon Sep 17 00:00:00 2001 From: Alexis Degrugillier Date: Sun, 21 Sep 2014 11:21:51 -0400 Subject: Add some comments It is a work in progress. I only did that for a single class so you can tell me if this is a good idea, if the content is missing something. Any comments are welcome. --- app/Controllers/configureController.php | 172 +++++++++++++++++++++++++++++++- 1 file changed, 170 insertions(+), 2 deletions(-) (limited to 'app') diff --git a/app/Controllers/configureController.php b/app/Controllers/configureController.php index 91b74aa29..8fae29ea2 100755 --- a/app/Controllers/configureController.php +++ b/app/Controllers/configureController.php @@ -1,6 +1,17 @@ view->loginOk) { Minz_Error::error( @@ -13,6 +24,17 @@ 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. + * If a category name is changed, it is updated. + */ public function categorizeAction() { $feedDAO = FreshRSS_Factory::createFeedDao(); $catDAO = new FreshRSS_CategoryDAO(); @@ -66,6 +88,28 @@ class FreshRSS_configure_Controller extends Minz_ActionController { Minz_View::prependTitle(Minz_Translate::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. + * + * @todo change the notification code + */ public function feedAction() { $catDAO = new FreshRSS_CategoryDAO(); $this->view->categories = $catDAO->listCategories(false); @@ -138,6 +182,33 @@ class FreshRSS_configure_Controller extends Minz_ActionController { } } + /** + * 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. + * + * @todo refactor to theme section to use the same syntax everywhere + * @todo change the notification code + */ public function displayAction() { if (Minz_Request::isPost()) { $this->view->conf->_language(Minz_Request::param('language', 'en')); @@ -178,6 +249,35 @@ class FreshRSS_configure_Controller extends Minz_ActionController { Minz_View::prependTitle(Minz_Translate::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. + * + * @todo change the notification code + */ public function readingAction() { if (Minz_Request::isPost()) { $this->view->conf->_posts_per_page(Minz_Request::param('posts_per_page', 10)); @@ -216,6 +316,15 @@ class FreshRSS_configure_Controller extends Minz_ActionController { Minz_View::prependTitle(Minz_Translate::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. + * + * @todo change the notification code + */ public function sharingAction() { if (Minz_Request::isPost()) { $params = Minz_Request::params(); @@ -235,6 +344,22 @@ class FreshRSS_configure_Controller extends Minz_ActionController { Minz_View::prependTitle(Minz_Translate::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. + * + * @todo remove numbers from the list of authorized shortcuts since they + * are used to access shortcuts and user queries + * @todo change the notification code + */ 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', @@ -271,10 +396,31 @@ class FreshRSS_configure_Controller extends Minz_ActionController { Minz_View::prependTitle(Minz_Translate::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') . ' · '); } + /** + * 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 + * @todo change the notification code + */ public function archivingAction() { if (Minz_Request::isPost()) { $old = Minz_Request::param('old_entries', 3); @@ -306,7 +452,17 @@ 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()); @@ -383,7 +539,19 @@ class FreshRSS_configure_Controller extends Minz_ActionController { Minz_View::prependTitle(Minz_Translate::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. + * + * @todo change the way of keeping lean data to have a more defensive + * code. At the moment, the code accepts any parameters and discard those + * on the black list. I think it is safer if we maintain a whitelist + * instead. + */ public function addQueryAction() { $queries = $this->view->conf->queries; $query = Minz_Request::params(); -- cgit v1.2.3 From cf01508fa58b5bdd85606fb766a79643a04ca6b7 Mon Sep 17 00:00:00 2001 From: Alexis Degrugillier Date: Sun, 21 Sep 2014 11:25:53 -0400 Subject: Fix typo --- app/Controllers/configureController.php | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'app') diff --git a/app/Controllers/configureController.php b/app/Controllers/configureController.php index 8fae29ea2..7340ca17a 100755 --- a/app/Controllers/configureController.php +++ b/app/Controllers/configureController.php @@ -206,7 +206,7 @@ class FreshRSS_configure_Controller extends Minz_ActionController { * - html5 notification timeout (default: 0) * Default values are false unless specified. * - * @todo refactor to theme section to use the same syntax everywhere + * @todo refactor theme section to use the same syntax everywhere * @todo change the notification code */ public function displayAction() { -- cgit v1.2.3 From bad165b0c424c9c650e22fec11ceecf1748d98e7 Mon Sep 17 00:00:00 2001 From: Alexis Degrugillier Date: Sun, 21 Sep 2014 11:28:46 -0400 Subject: Add a todo --- app/Controllers/configureController.php | 2 ++ 1 file changed, 2 insertions(+) (limited to 'app') diff --git a/app/Controllers/configureController.php b/app/Controllers/configureController.php index 7340ca17a..99c72d869 100755 --- a/app/Controllers/configureController.php +++ b/app/Controllers/configureController.php @@ -420,6 +420,8 @@ class FreshRSS_configure_Controller extends Minz_ActionController { * @todo explain why the default value is -2 but this value does not * exist in the drop-down list * @todo change the notification code + * @todo refactor configuration setting syntax to be consistent with the + * other methods */ public function archivingAction() { if (Minz_Request::isPost()) { -- cgit v1.2.3 From 0420a989391c9af30ee6d85638c81bfb4f605132 Mon Sep 17 00:00:00 2001 From: Alexis Degrugillier 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(+) (limited to 'app') 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 @@ 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 From 5889ef35c8ecbbae948420af9f2b05e7010593ae Mon Sep 17 00:00:00 2001 From: Alexis Degrugillier Date: Sun, 21 Sep 2014 12:01:36 -0400 Subject: Change todo align --- app/Controllers/configureController.php | 14 +++++++------- app/Controllers/statsController.php | 2 +- 2 files changed, 8 insertions(+), 8 deletions(-) (limited to 'app') diff --git a/app/Controllers/configureController.php b/app/Controllers/configureController.php index 99c72d869..7b8dd672f 100755 --- a/app/Controllers/configureController.php +++ b/app/Controllers/configureController.php @@ -10,7 +10,7 @@ class FreshRSS_configure_Controller extends Minz_ActionController { * underlying framework. * * @todo see if the category default configuration is needed here or if - * we can move it to the categorize action + * we can move it to the categorize action */ public function firstAction() { if (!$this->view->loginOk) { @@ -357,7 +357,7 @@ class FreshRSS_configure_Controller extends Minz_ActionController { * tab and up. * * @todo remove numbers from the list of authorized shortcuts since they - * are used to access shortcuts and user queries + * are used to access shortcuts and user queries * @todo change the notification code */ public function shortcutAction() { @@ -418,10 +418,10 @@ class FreshRSS_configure_Controller extends Minz_ActionController { * - refresh frequency (default: -2) * * @todo explain why the default value is -2 but this value does not - * exist in the drop-down list + * exist in the drop-down list * @todo change the notification code * @todo refactor configuration setting syntax to be consistent with the - * other methods + * other methods */ public function archivingAction() { if (Minz_Request::isPost()) { @@ -550,9 +550,9 @@ class FreshRSS_configure_Controller extends Minz_ActionController { * lean data. * * @todo change the way of keeping lean data to have a more defensive - * code. At the moment, the code accepts any parameters and discard those - * on the black list. I think it is safer if we maintain a whitelist - * instead. + * code. At the moment, the code accepts any parameters and discard + * those on the black list. I think it is safer if we maintain a + * whitelist instead. */ public function addQueryAction() { $queries = $this->view->conf->queries; diff --git a/app/Controllers/statsController.php b/app/Controllers/statsController.php index 64f66f2fa..256543f37 100644 --- a/app/Controllers/statsController.php +++ b/app/Controllers/statsController.php @@ -91,7 +91,7 @@ class FreshRSS_stats_Controller extends Minz_ActionController { * - month * * @todo verify that the metrics used here make some sense. Especially - * for the average. + * for the average. */ public function repartitionAction() { $statsDAO = FreshRSS_Factory::createStatsDAO(); -- cgit v1.2.3