Skip to content

Commit 419e891

Browse files
jeandatjeandat
committed
features/doc — Added missing comments.
1 parent 3b41bd6 commit 419e891

27 files changed

+108
-26
lines changed

‎app/app.config.js

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -141,6 +141,8 @@
141141
}
142142

143143
function httpConfig($httpProvider) {
144+
// Performance optimisation: batch multiple $http responses into one $digest when possible
145+
// http://blog.thoughtram.io/angularjs/2015/01/14/exploring-angular-1.3-speed-up-with-applyAsync.html
144146
$httpProvider.useApplyAsync(true);
145147
$httpProvider.interceptors.push('httpInterceptor');
146148
}

‎app/app.constant.js

Lines changed: 10 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -3,19 +3,26 @@
33

44
angular
55
.module('app')
6-
// App version from package.json
6+
// Lodash for dependency injection
77
.constant('_', _)
8+
// App version from package.json
89
.constant('version', '@@version')
910
.constant('stringify', stringify)
11+
// Google Analytics account ID
1012
.constant('trackerId', '@@trackerId')
11-
.constant('env', '@@env')
13+
// Current environment (dev or dist)
14+
.constant('env', '@@env')
15+
// Backend endpoint (local pc in livereload mode - proxy - or Marvel servers)
1216
.constant('apiEndpoint', '@@apiEndpoint')
17+
// Marvel API key
1318
.constant('apiKey', '@@apiKey')
14-
// Oups, I did it again
19+
// Marvel private API key (yeah I know, but Marvel forced my hand)
1520
.constant('privateApiKey', '@@privateApiKey')
1621
// Marvel default offset when requesting a list of results (number of items)
1722
.constant('defaultPageSize', 10)
23+
// HTTP cache name
1824
.constant('defaultCacheName', 'defaultCache')
25+
// Firebase configuration
1926
.constant('firebaseApiKey', 'AIzaSyCgo-Ta3byIK8w9I9g0o3Hrgop70-Ajm-8')
2027
.constant('firebaseAuthDomain', 'learning-ionic.firebaseapp.com')
2128
.constant('firebaseDatabaseUrl', 'https://learning-ionic.firebaseio.com')

‎app/app.run.js

Lines changed: 5 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -24,7 +24,7 @@
2424
cordova.plugins.Keyboard.disableScroll(false);
2525
}
2626

27-
// Style status bar
27+
// Style the status bar
2828
var style = _.get($cordovaStatusbar, 'style');
2929
style && style(1);
3030
}
@@ -73,6 +73,7 @@
7373
}
7474
}
7575

76+
// Help to detect in console which states have been invoked.
7677
function setCustomLogs($rootScope, $log) {
7778
$rootScope.$on('$stateChangeStart', logViewName);
7879

@@ -184,10 +185,12 @@
184185
}
185186
}
186187

188+
// Apply saved settings at startup.
187189
function applySettings(settingService) {
188190
settingService.apply();
189191
}
190192

193+
// Set up Google Analytics
191194
function setTracker($log, trackerId, $rootScope, $cordovaGoogleAnalytics) {
192195

193196
$cordovaGoogleAnalytics.startTrackerWithId(trackerId);
@@ -214,6 +217,7 @@
214217
}
215218
}
216219

220+
// Boot workflow that will initialize several components, go to the home page and then hide the splashscreen.
217221
function boot($state, $cordovaSplashscreen, $timeout, ImgCache, $rootScope, $log, $ionicPopup, favouriteService, Err, showErr) {
218222
initImgCache()
219223
.catch(explain)

‎app/character/character.factory.js

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -5,7 +5,7 @@
55
.module('app')
66
.factory('characterService', factory);
77

8-
8+
// Service to request characters from the Marvel API.
99
function factory(Restangular, utils, defaultPageSize) {
1010
var characters = Restangular.all('characters');
1111

@@ -17,7 +17,8 @@
1717

1818
///////////////
1919

20-
// Search characters which name starts with `name`.
20+
// Search characters which name starts with `prefix`.
21+
// Accept a single option `offset` which is the position of the first result.
2122
function findByName(prefix, offset) {
2223
var criteria = {limit: defaultPageSize};
2324
prefix && (criteria.nameStartsWith = prefix);

‎app/character/character.run.js

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -7,6 +7,7 @@
77

88
///////////////
99

10+
// Extend the Character model object from Restangular with new functions.
1011
function addNewMethodsToCharacters(Restangular, favouriteService) {
1112
Restangular.extendModel('characters', function (model) {
1213
model.thumbnailUrl = getThumbnailUrl();
@@ -16,14 +17,17 @@
1617

1718
/////////////
1819

20+
// Create and cache a usable value for the thumbnail image avoiding concatenating the value every time.
1921
function getThumbnailUrl() {
2022
var tnl = model.thumbnail;
2123
if(_.isEmpty(tnl) || _.endsWith(tnl.path, 'image_not_available')) return '';
2224
return tnl.path + '.' + tnl.extension;
2325
}
26+
// Create and cache a usable value for the detail url avoiding concatenating the value every time.
2427
function getDetailUrl(){
2528
return _.get(_.find(model.urls, {type:'detail'}), 'url');
2629
}
30+
// Return the favourite associated to this model in Firebase.
2731
function getFavourite(){
2832
return favouriteService.getFaveByModelId(model.id);
2933
}

‎app/character/comic-list/character-comic-list.controller.js

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -29,6 +29,7 @@
2929
unlisten = $scope.$parent.$on('modal.shown', showMore);
3030
}
3131

32+
// Request new comics for the character.
3233
function showMore() {
3334
if (unlisten) {
3435
unlisten();

‎app/character/detail/character-detail.controller.js

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -42,6 +42,7 @@
4242
open(vm.character.detailUrl, '_system');
4343
}
4444

45+
// Request the first five comics for this character.
4546
function loadComics() {
4647
unlisten();
4748
$timeout(waitAnimationEnd, 500);

‎app/character/list/character-list.controller.js

Lines changed: 7 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -35,6 +35,7 @@
3535
$rootScope.$on('firebase:ready', checkFavourites);
3636
}
3737

38+
// Search for characters whose name starts with…
3839
function search() {
3940
showSpinner();
4041
var promise = characterService.findByName(vm.filter);
@@ -63,6 +64,7 @@
6364
vm.searching = false;
6465
}
6566

67+
// Request new items for the current search.
6668
function showMore() {
6769
showSpinner();
6870
vm.offset += defaultPageSize;
@@ -72,6 +74,7 @@
7274
.finally(hideSpinner);
7375
}
7476

77+
// Concatenate current results with new ones. Update meta infos.
7578
function updateList(results) {
7679
var meta = _.get(results, 'meta');
7780
$log.info('Loaded', (meta.count + meta.offset), '/', meta.total, 'characters which name starts with `' +
@@ -85,7 +88,7 @@
8588
}
8689

8790
// Event handler called when clicking the fave button (heart).
88-
// It will add or remove a favourite in our local db.
91+
// It will add or remove a favourite in Firebase.
8992
function toggleFave(character) {
9093
if (character.favourite) {
9194
favouriteService.removeFave(character.favourite);
@@ -97,6 +100,7 @@
97100
}
98101
}
99102

103+
// Indicate us a fave has been added in Firebase (at least locally).
100104
function favouriteDidAdded(event, fave) {
101105
// Nothing to do if there is zero characters.
102106
if (!vm.characters.length) return;
@@ -105,6 +109,7 @@
105109
$log.debug('Fave added:', fave);
106110
}
107111

112+
// Indicate us a fave has been removed in Firebase (at least locally).
108113
function favouriteDidRemoved(event, fave) {
109114
var model = _.find(vm.characters, {id: fave.id});
110115
if (model) model.favourite = null;
@@ -118,6 +123,7 @@
118123
});
119124
}
120125

126+
// Get the corresponding fave in Firebase (if any) for each model.
121127
function checkFavourites(){
122128
_.forEach(vm.characters, updateFavourite);
123129
/////////

‎app/comic/comic.factory.js

Lines changed: 4 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -5,6 +5,7 @@
55
.module('app')
66
.factory('comicService', factory);
77

8+
// Service to request comics from the Marvel API.
89
function factory(Restangular, Err, utils, defaultPageSize) {
910

1011
var comics = Restangular.all('comics');
@@ -19,6 +20,7 @@
1920
///////////////
2021

2122
// Search comics which name starts with `name`.
23+
// `options` is an hash which accepts any value accepted by the Marvel service.
2224
function findByName(prefix, options) {
2325
var criteria = _.defaults(options, {
2426
format: 'comic',
@@ -30,7 +32,8 @@
3032
return comics.getList(criteria).then(utils.cacheThumbnails);
3133
}
3234

33-
// Search comics which name starts with `name`.
35+
// Search comics which id is `id`.
36+
// `options` is an hash which accepts any value accepted by the Marvel service.
3437
function findByCharacterId(id, options) {
3538
if (!id) throw new Err(1004, {missing: 'id'});
3639
var criteria = _.defaults(options, {

‎app/comic/comic.run.js

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -7,6 +7,7 @@
77

88
///////////////
99

10+
// Extend the Comic model object from Restangular with new functions.
1011
function addNewMethodsToComics(Restangular, favouriteService) {
1112
Restangular.extendModel('comics', function (model) {
1213
model.thumbnailUrl = getThumbnailUrl();
@@ -18,22 +19,27 @@
1819

1920
/////////////
2021

22+
// Create and cache a usable value for the thumbnail image avoiding concatenating the value every time.
2123
function getThumbnailUrl() {
2224
var tnl = model.thumbnail;
2325
if (_.isEmpty(tnl) || _.endsWith(tnl.path, 'image_not_available')) return '';
2426
return tnl.path + '.' + tnl.extension;
2527
}
28+
// Create and cache a usable value for a thumbnail image (format 'portrait_uncanny') avoiding concatenating the value every time.
2629
function getThumbnailUrlInPortraitUncanny(){
2730
var tnl = model.thumbnail;
2831
if (_.isEmpty(tnl) || _.endsWith(tnl.path, 'image_not_available')) return '';
2932
return tnl.path + '/portrait_uncanny.' + tnl.extension;
3033
}
34+
// Create and cache a usable value for the detail url avoiding concatenating the value every time.
3135
function getDetailUrl(){
3236
return _.get(_.find(model.urls, {type:'detail'}), 'url');
3337
}
38+
// Create and cache a usable value for the print price avoiding concatenating the value every time.
3439
function getPrintPrice(){
3540
return _.get(_.find(model.prices, {type: 'printPrice'}), 'price');
3641
}
42+
// Return the favourite associated to this model in Firebase.
3743
function getFavourite(){
3844
return favouriteService.getFaveByModelId(model.id);
3945
}

‎app/comic/detail/comic-detail.controller.js

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -23,6 +23,7 @@
2323
$log.debug(vm.title + ' instantiated');
2424
}
2525

26+
// Open comic page on marvel.com in default browser.
2627
function openDetailPage() {
2728
var open = _.get(window, 'cordova.InAppBrowser.open') || window.open;
2829
open(vm.comic.detailUrl, '_system');
@@ -41,7 +42,7 @@
4142
vm.hideContent = !vm.hideContent;
4243
}
4344

44-
// Show a native viewer with zoom capability.
45+
// Show a native viewer with zoom and sharing capabilities.
4546
function showViewer() {
4647
// Unfortunately, this plugin doesn't handle cdvfile: url.
4748
// So I'm converting it to a normal file system url to avoid to download again that image.

‎app/comic/list/comic-list.controller.js

Lines changed: 7 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -16,7 +16,6 @@
1616
vm.searching = false;
1717
vm.offset = 0;
1818
vm.hasMoreData = false;
19-
vm.keep = keep;
2019
vm.search = search;
2120
vm.loadMore = loadMore;
2221
vm.toggleFave = toggleFave;
@@ -36,10 +35,7 @@
3635
$rootScope.$on('firebase:ready', checkFavourites);
3736
}
3837

39-
function keep() {
40-
$cordovaToast.showShortBottom('Not implemented yet…');
41-
}
42-
38+
// Search for comics whose name starts with…
4339
function search() {
4440
showSpinner();
4541
var promise = comicService.findByName(vm.filter);
@@ -69,6 +65,7 @@
6965
vm.searching = false;
7066
}
7167

68+
// Request new items for the current search.
7269
function loadMore() {
7370
showSpinner();
7471
vm.offset += defaultPageSize;
@@ -78,6 +75,7 @@
7875
.finally(hideSpinner);
7976
}
8077

78+
// Concatenate current results with new ones. Update meta infos.
8179
function updateList(results) {
8280
var meta = _.get(results, 'meta');
8381
$log.info('Loaded', (meta.count + meta.offset), '/', meta.total, 'comics which title starts with `' +
@@ -91,7 +89,7 @@
9189
}
9290

9391
// Event handler called when clicking the fave button (heart).
94-
// It will add or remove a favourite in our local db.
92+
// It will add or remove a favourite in Firebase.
9593
function toggleFave(comic) {
9694
if (comic.favourite) {
9795
favouriteService.removeFave(comic.favourite);
@@ -103,6 +101,7 @@
103101
}
104102
}
105103

104+
// Indicate us a fave has been added in Firebase (at least locally).
106105
function favouriteDidAdded(event, fave) {
107106
// Nothing to do if there is zero comics.
108107
if (!vm.comics.length) return;
@@ -111,6 +110,7 @@
111110
$log.debug('Fave added:', fave);
112111
}
113112

113+
// Indicate us a fave has been removed in Firebase (at least locally).
114114
function favouriteDidRemoved(event, fave) {
115115
var model = _.find(vm.comics, {id: fave.id});
116116
if (model) model.favourite = null;
@@ -124,6 +124,7 @@
124124
});
125125
}
126126

127+
// Get the corresponding fave in Firebase (if any) for each model.
127128
function checkFavourites(){
128129
_.forEach(vm.comics, updateFavourite);
129130
/////////

‎app/common/back-button/back-button.directive.js

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -5,6 +5,8 @@
55
.module('app')
66
.directive('backButton', factory);
77

8+
// Back button component that do what Ionic do automatically in the navbar : show a back button which respects guidelines from the
9+
// platform currently active.
810
function factory() {
911

1012
var directive = {

‎app/common/error/err.factory.js

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -5,6 +5,7 @@
55
.module('app')
66
.factory('Err', createClass);
77

8+
// Enhanced Error class.
89
function createClass($interpolate) {
910

1011
var codes = {

‎app/common/error/exception-handler.decorator.js

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -9,6 +9,7 @@
99

1010
$exceptionHandlerDecorator.$inject = ['$delegate', '$log', 'showErr'];
1111

12+
// Default angular handler for uncatched exceptions. Render a native toast.
1213
function $exceptionHandlerDecorator($delegate, $log, showErr) {
1314

1415
function exceptionHandler(exception, cause) {

‎app/common/error/http-interceptor.factory.js

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -5,6 +5,7 @@
55
.module('app')
66
.factory('httpInterceptor', httpInterceptor);
77

8+
// Normalize and transform network errors.
89
function httpInterceptor(Err, $q, $log) {
910
return {
1011
requestError: function () {

‎app/common/error/show-err.factory.js

Lines changed: 1 addition & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -7,9 +7,7 @@
77

88
/////////
99

10-
// Dumb function that take an error and throw it.
11-
// Can be used in conjunction with a catch block for instance when the only think you want to do
12-
// is throw whatever comes in.
10+
// Render a native toast for the given exception.
1311
function factory($injector) {
1412
return function showErr(exception) {
1513

‎app/common/hide-content/hide-content.directive.js

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -5,6 +5,7 @@
55
.module('app')
66
.directive('hideContent', ddf);
77

8+
// Directive that will hide content from its container depending on the expression value.
89
function ddf() {
910

1011
var directive = {

0 commit comments

Comments
 (0)