features/doc — Added missing comments.

jeandat · Aug 3, 2016 · 419e891 · 419e891
1 parent 3b41bd6
commit 419e891
Show file tree

Hide file tree

Showing 27 changed files with 108 additions and 26 deletions.
diff --git a/app/app.config.js b/app/app.config.js
@@ -141,6 +141,8 @@
     }
 
     function httpConfig($httpProvider) {
+        // Performance optimisation: batch multiple $http responses into one $digest when possible
+        // http://blog.thoughtram.io/angularjs/2015/01/14/exploring-angular-1.3-speed-up-with-applyAsync.html
         $httpProvider.useApplyAsync(true);
         $httpProvider.interceptors.push('httpInterceptor');
     }

diff --git a/app/app.constant.js b/app/app.constant.js
@@ -3,19 +3,26 @@
 
     angular
         .module('app')
-        // App version from package.json
+        // Lodash for dependency injection
         .constant('_', _)
+        // App version from package.json
         .constant('version', '@@version')
         .constant('stringify', stringify)
+        // Google Analytics account ID
 		.constant('trackerId', '@@trackerId')
-		.constant('env', '@@env')
+		// Current environment (dev or dist)
+        .constant('env', '@@env')
+        // Backend endpoint (local pc in livereload mode - proxy - or Marvel servers)
 		.constant('apiEndpoint', '@@apiEndpoint')
+        // Marvel API key
 		.constant('apiKey', '@@apiKey')
-        // Oups, I did it again
+        // Marvel private API key (yeah I know, but Marvel forced my hand)
 		.constant('privateApiKey', '@@privateApiKey')
         // Marvel default offset when requesting a list of results (number of items)
         .constant('defaultPageSize', 10)
+        // HTTP cache name
         .constant('defaultCacheName', 'defaultCache')
+        // Firebase configuration
         .constant('firebaseApiKey', 'AIzaSyCgo-Ta3byIK8w9I9g0o3Hrgop70-Ajm-8')
         .constant('firebaseAuthDomain', 'learning-ionic.firebaseapp.com')
         .constant('firebaseDatabaseUrl', 'https://learning-ionic.firebaseio.com')

diff --git a/app/app.run.js b/app/app.run.js
@@ -24,7 +24,7 @@
             cordova.plugins.Keyboard.disableScroll(false);
         }
 
-        // Style status bar
+        // Style the status bar
         var style = _.get($cordovaStatusbar, 'style');
         style && style(1);
     }
@@ -73,6 +73,7 @@
         }
     }
 
+    // Help to detect in console which states have been invoked.
     function setCustomLogs($rootScope, $log) {
         $rootScope.$on('$stateChangeStart', logViewName);
 
@@ -184,10 +185,12 @@
         }
     }
 
+    // Apply saved settings at startup.
     function applySettings(settingService) {
         settingService.apply();
     }
 
+    // Set up Google Analytics
     function setTracker($log, trackerId, $rootScope, $cordovaGoogleAnalytics) {
 
         $cordovaGoogleAnalytics.startTrackerWithId(trackerId);
@@ -214,6 +217,7 @@
         }
     }
 
+    // Boot workflow that will initialize several components, go to the home page and then hide the splashscreen.
     function boot($state, $cordovaSplashscreen, $timeout, ImgCache, $rootScope, $log, $ionicPopup, favouriteService, Err, showErr) {
         initImgCache()
             .catch(explain)

diff --git a/app/character/character.factory.js b/app/character/character.factory.js
@@ -5,7 +5,7 @@
         .module('app')
         .factory('characterService', factory);
 
-
+    // Service to request characters from the Marvel API.
     function factory(Restangular, utils, defaultPageSize) {
         var characters = Restangular.all('characters');
 
@@ -17,7 +17,8 @@
 
         ///////////////
 
-        // Search characters which name starts with `name`.
+        // Search characters which name starts with `prefix`.
+        // Accept a single option `offset` which is the position of the first result. 
         function findByName(prefix, offset) {
             var criteria = {limit: defaultPageSize};
             prefix && (criteria.nameStartsWith = prefix);

diff --git a/app/character/character.run.js b/app/character/character.run.js
@@ -7,6 +7,7 @@
 
     ///////////////
 
+    // Extend the Character model object from Restangular with new functions.
     function addNewMethodsToCharacters(Restangular, favouriteService) {
         Restangular.extendModel('characters', function (model) {
             model.thumbnailUrl = getThumbnailUrl();
@@ -16,14 +17,17 @@
 
             /////////////
 
+            // Create and cache a usable value for the thumbnail image avoiding concatenating the value every time. 
             function getThumbnailUrl() {
                 var tnl = model.thumbnail;
                 if(_.isEmpty(tnl) || _.endsWith(tnl.path, 'image_not_available')) return '';
                 return tnl.path + '.' + tnl.extension;
             }
+            // Create and cache a usable value for the detail url avoiding concatenating the value every time.
             function getDetailUrl(){
                 return _.get(_.find(model.urls, {type:'detail'}), 'url');
             }
+            // Return the favourite associated to this model in Firebase.
             function getFavourite(){
                 return favouriteService.getFaveByModelId(model.id);
             }

diff --git a/app/character/comic-list/character-comic-list.controller.js b/app/character/comic-list/character-comic-list.controller.js
@@ -29,6 +29,7 @@
             unlisten = $scope.$parent.$on('modal.shown', showMore);
         }
 
+        // Request new comics for the character.
         function showMore() {
             if (unlisten) {
                 unlisten();

diff --git a/app/character/detail/character-detail.controller.js b/app/character/detail/character-detail.controller.js
@@ -42,6 +42,7 @@
             open(vm.character.detailUrl, '_system');
         }
 
+        // Request the first five comics for this character. 
         function loadComics() {
             unlisten();
             $timeout(waitAnimationEnd, 500);

diff --git a/app/character/list/character-list.controller.js b/app/character/list/character-list.controller.js
@@ -35,6 +35,7 @@
             $rootScope.$on('firebase:ready', checkFavourites);
         }
 
+        // Search for characters whose name starts with…
         function search() {
             showSpinner();
             var promise = characterService.findByName(vm.filter);
@@ -63,6 +64,7 @@
             vm.searching = false;
         }
 
+        // Request new items for the current search.
         function showMore() {
             showSpinner();
             vm.offset += defaultPageSize;
@@ -72,6 +74,7 @@
                 .finally(hideSpinner);
         }
 
+        // Concatenate current results with new ones. Update meta infos.
         function updateList(results) {
             var meta = _.get(results, 'meta');
             $log.info('Loaded', (meta.count + meta.offset), '/', meta.total, 'characters which name starts with `' +
@@ -85,7 +88,7 @@
         }
 
         // Event handler called when clicking the fave button (heart).
-        // It will add or remove a favourite in our local db.
+        // It will add or remove a favourite in Firebase.
         function toggleFave(character) {
             if (character.favourite) {
                 favouriteService.removeFave(character.favourite);
@@ -97,6 +100,7 @@
             }
         }
 
+        // Indicate us a fave has been added in Firebase (at least locally).
         function favouriteDidAdded(event, fave) {
             // Nothing to do if there is zero characters.
             if (!vm.characters.length) return;
@@ -105,6 +109,7 @@
             $log.debug('Fave added:', fave);
         }
 
+        // Indicate us a fave has been removed in Firebase (at least locally).
         function favouriteDidRemoved(event, fave) {
             var model = _.find(vm.characters, {id: fave.id});
             if (model) model.favourite = null;
@@ -118,6 +123,7 @@
             });
         }
 
+        // Get the corresponding fave in Firebase (if any) for each model.
         function checkFavourites(){
             _.forEach(vm.characters, updateFavourite);
             /////////

diff --git a/app/comic/comic.factory.js b/app/comic/comic.factory.js
@@ -5,6 +5,7 @@
         .module('app')
         .factory('comicService', factory);
 
+    // Service to request comics from the Marvel API. 
     function factory(Restangular, Err, utils, defaultPageSize) {
 
         var comics = Restangular.all('comics');
@@ -19,6 +20,7 @@
         ///////////////
 
         // Search comics which name starts with `name`.
+        // `options` is an hash which accepts any value accepted by the Marvel service. 
         function findByName(prefix, options) {
             var criteria = _.defaults(options, {
                 format: 'comic',
@@ -30,7 +32,8 @@
             return comics.getList(criteria).then(utils.cacheThumbnails);
         }
 
-        // Search comics which name starts with `name`.
+        // Search comics which id is `id`.
+        // `options` is an hash which accepts any value accepted by the Marvel service.
         function findByCharacterId(id, options) {
             if (!id) throw new Err(1004, {missing: 'id'});
             var criteria = _.defaults(options, {

diff --git a/app/comic/comic.run.js b/app/comic/comic.run.js
@@ -7,6 +7,7 @@
 
     ///////////////
 
+    // Extend the Comic model object from Restangular with new functions.
     function addNewMethodsToComics(Restangular, favouriteService) {
         Restangular.extendModel('comics', function (model) {
             model.thumbnailUrl = getThumbnailUrl();
@@ -18,22 +19,27 @@
 
             /////////////
 
+            // Create and cache a usable value for the thumbnail image avoiding concatenating the value every time. 
             function getThumbnailUrl() {
                 var tnl = model.thumbnail;
                 if (_.isEmpty(tnl) || _.endsWith(tnl.path, 'image_not_available')) return '';
                 return tnl.path + '.' + tnl.extension;
             }
+            // Create and cache a usable value for a thumbnail image (format 'portrait_uncanny') avoiding concatenating the value every time.
             function getThumbnailUrlInPortraitUncanny(){
                 var tnl = model.thumbnail;
                 if (_.isEmpty(tnl) || _.endsWith(tnl.path, 'image_not_available')) return '';
                 return tnl.path + '/portrait_uncanny.' + tnl.extension;
             }
+            // Create and cache a usable value for the detail url avoiding concatenating the value every time.
             function getDetailUrl(){
                 return _.get(_.find(model.urls, {type:'detail'}), 'url');
             }
+            // Create and cache a usable value for the print price avoiding concatenating the value every time.
             function getPrintPrice(){
                 return _.get(_.find(model.prices, {type: 'printPrice'}), 'price');
             }
+            // Return the favourite associated to this model in Firebase.
             function getFavourite(){
                 return favouriteService.getFaveByModelId(model.id);
             }

diff --git a/app/comic/detail/comic-detail.controller.js b/app/comic/detail/comic-detail.controller.js
@@ -23,6 +23,7 @@
             $log.debug(vm.title + ' instantiated');
         }
 
+        // Open comic page on marvel.com in default browser.
         function openDetailPage() {
             var open = _.get(window, 'cordova.InAppBrowser.open') || window.open;
             open(vm.comic.detailUrl, '_system');
@@ -41,7 +42,7 @@
             vm.hideContent = !vm.hideContent;
         }
 
-        // Show a native viewer with zoom capability.
+        // Show a native viewer with zoom and sharing capabilities.
         function showViewer() {
             // Unfortunately, this plugin doesn't handle cdvfile: url.
             // So I'm converting it to a normal file system url to avoid to download again that image.

diff --git a/app/comic/list/comic-list.controller.js b/app/comic/list/comic-list.controller.js
@@ -16,7 +16,6 @@
         vm.searching = false;
         vm.offset = 0;
         vm.hasMoreData = false;
-        vm.keep = keep;
         vm.search = search;
         vm.loadMore = loadMore;
         vm.toggleFave = toggleFave;
@@ -36,10 +35,7 @@
             $rootScope.$on('firebase:ready', checkFavourites);
         }
 
-        function keep() {
-            $cordovaToast.showShortBottom('Not implemented yet…');
-        }
-
+        // Search for comics whose name starts with…
         function search() {
             showSpinner();
             var promise = comicService.findByName(vm.filter);
@@ -69,6 +65,7 @@
             vm.searching = false;
         }
 
+        // Request new items for the current search.
         function loadMore() {
             showSpinner();
             vm.offset += defaultPageSize;
@@ -78,6 +75,7 @@
                 .finally(hideSpinner);
         }
 
+        // Concatenate current results with new ones. Update meta infos.
         function updateList(results) {
             var meta = _.get(results, 'meta');
             $log.info('Loaded', (meta.count + meta.offset), '/', meta.total, 'comics which title starts with `' +
@@ -91,7 +89,7 @@
         }
 
         // Event handler called when clicking the fave button (heart).
-        // It will add or remove a favourite in our local db.
+        // It will add or remove a favourite in Firebase.
         function toggleFave(comic) {
             if (comic.favourite) {
                 favouriteService.removeFave(comic.favourite);
@@ -103,6 +101,7 @@
             }
         }
 
+        // Indicate us a fave has been added in Firebase (at least locally).
         function favouriteDidAdded(event, fave) {
             // Nothing to do if there is zero comics.
             if (!vm.comics.length) return;
@@ -111,6 +110,7 @@
             $log.debug('Fave added:', fave);
         }
 
+        // Indicate us a fave has been removed in Firebase (at least locally).
         function favouriteDidRemoved(event, fave) {
             var model = _.find(vm.comics, {id: fave.id});
             if (model) model.favourite = null;
@@ -124,6 +124,7 @@
             });
         }
 
+        // Get the corresponding fave in Firebase (if any) for each model.
         function checkFavourites(){
             _.forEach(vm.comics, updateFavourite);
             /////////

diff --git a/app/common/back-button/back-button.directive.js b/app/common/back-button/back-button.directive.js
@@ -5,6 +5,8 @@
         .module('app')
         .directive('backButton', factory);
 
+    // Back button component that do what Ionic do automatically in the navbar : show a back button which respects guidelines from the
+    // platform currently active.
     function factory() {
 
         var directive = {

diff --git a/app/common/error/err.factory.js b/app/common/error/err.factory.js
@@ -5,6 +5,7 @@
         .module('app')
         .factory('Err', createClass);
 
+    // Enhanced Error class.
     function createClass($interpolate) {
 
         var codes = {

diff --git a/app/common/error/exception-handler.decorator.js b/app/common/error/exception-handler.decorator.js
@@ -9,6 +9,7 @@
 
     $exceptionHandlerDecorator.$inject = ['$delegate', '$log', 'showErr'];
 
+    // Default angular handler for uncatched exceptions. Render a native toast.
     function $exceptionHandlerDecorator($delegate, $log, showErr) {
 
         function exceptionHandler(exception, cause) {

diff --git a/app/common/error/http-interceptor.factory.js b/app/common/error/http-interceptor.factory.js
@@ -5,6 +5,7 @@
         .module('app')
         .factory('httpInterceptor', httpInterceptor);
 
+    // Normalize and transform network errors.
     function httpInterceptor(Err, $q, $log) {
         return {
             requestError: function () {

diff --git a/app/common/error/show-err.factory.js b/app/common/error/show-err.factory.js
@@ -7,9 +7,7 @@
 
     /////////
 
-    // Dumb function that take an error and throw it.
-    // Can be used in conjunction with a catch block for instance when the only think you want to do
-    // is throw whatever comes in.
+    // Render a native toast for the given exception.
     function factory($injector) {
         return function showErr(exception) {
 

diff --git a/app/common/hide-content/hide-content.directive.js b/app/common/hide-content/hide-content.directive.js
@@ -5,6 +5,7 @@
         .module('app')
         .directive('hideContent', ddf);
 
+    // Directive that will hide content from its container depending on the expression value.
     function ddf() {
 
         var directive = {