From 25f355701ebdf697b88cb822f314f712854d7655 Mon Sep 17 00:00:00 2001
From: kritika bahl <kritika.bahlnearbuy.com>
Date: Sun, 3 Apr 2016 17:38:40 +0530
Subject: [PATCH 1/2] documentation

---
 Gruntfile.js                             |  21 +++-
 README.md                                | 129 +++++++++++++++++++++++
 app/scripts/decorators/$log-decorator.js |   3 +-
 app/scripts/services/StackTrace.js       |  18 +++-
 app/scripts/services/logger-levels.js    |  16 +++
 app/scripts/services/logger-utils.js     |  31 +++++-
 app/scripts/services/logger.js           |  66 +++++++++++-
 app/scripts/services/source-map-util.js  |  35 +++++-
 app/scripts/services/source-map.js       |   2 +-
 9 files changed, 310 insertions(+), 11 deletions(-)

diff --git a/Gruntfile.js b/Gruntfile.js
index d315c57..32e4ac2 100644
--- a/Gruntfile.js
+++ b/Gruntfile.js
@@ -17,6 +17,7 @@ module.exports = function (grunt) {
   grunt.loadNpmTasks('grunt-angular-architecture-graph');
   grunt.loadNpmTasks('grunt-bump');
   grunt.loadNpmTasks('grunt-jsinspect');
+  grunt.loadNpmTasks('grunt-ngdocs');
 
   grunt.loadNpmTasks('grunt-istanbul-coverage');
   // Configurable paths for the application
@@ -186,6 +187,23 @@ module.exports = function (grunt) {
         src: ['test/spec/{,*/}*.js']
       }
     },
+    ngdocs: {
+      options: {
+        dest: 'docs',
+        scripts: ['<%= yeoman.dist %>/scripts/vendor.js','<%= yeoman.dist %>/scripts/ui.logger.js','bower_components/angular-mocks/angular-mocks.js'],
+        html5Mode: false,
+        startPage: '/api/logger',
+        title:" Docs",
+        inlinePartials: true,
+        bestMatch: true,
+        sourceLink:true,
+        editLink:true,editExample:true
+      },
+      api: {
+        src: ['<%= yeoman.app %>/**/*.js'],
+        title: 'API Documentation'
+      }
+    },
 
     // Empties folders to start fresh
     clean: {
@@ -471,7 +489,8 @@ module.exports = function (grunt) {
     'uglify',
     //'filerev',
     'usemin',
-    'htmlmin'//,
+    'htmlmin',
+    'ngdocs'
     //'angular_architecture_graph'
   ]);
 
diff --git a/README.md b/README.md
index eb13af3..1350a64 100644
--- a/README.md
+++ b/README.md
@@ -23,6 +23,11 @@
 ```javascript
     bower install ng-ui-logger
     <script src="bower_components/ui-logger/dist/scripts/ui-logger.js"></script>
+    
+    Add `ui.logger` to your list of dependencies.
+    
+    angular.module('test',['ui.logger'])
+    
 ```
 #### CDN
 
@@ -31,6 +36,130 @@
 * https://rawgit.com/angular-libs/ui-logger/master/dist/scripts/ui-logger.js
 * https://rawgit.com/angular-libs/ui-logger/master/dist/scripts/ui-logger.min.js
 
+#### Usage
+
+`ui.logger` module can be used to obtain the log data ( logger instance name,time,url,errorMessage,stackframes) for the exceptions occurring in your angular application.The module provides multiple options to easily accomplish front-end logging for different use cases.Given below are some basic examples to get one started with using `ui.logger` module -
+
+
+
+**(1)** First of all, Include `ui.logger` as a dependency to your module. Further wrap the code that can generate exception in a `try block`  and you can carry out the logging process in `catch block`. The module extends the functionality of `$log` service of AngularJs and helps you write the informative log data corresponding to the exception on console using `$log` service. Use `$log` methods like debug(),info(),warn(),log(),error() depending on the severity of error.
+
+```javascript
+angular.module('test',['ui.logger']).run(['$log', function testRun($log){
+  try{
+    throw new TypeError('error ...!!!');
+  }catch(err){
+    $log.debug(err);
+  }
+}]);
+```
+
+
+**(2)** `$log` service should be used only if basic logging with one global default instance of logger serves your purpose.You can create a new instance of logger using `getInstance()` method of `logger` service of `ui.logger`. If you wish to give the instance a particular name, pass the same as an argument to the `getInstance()` method. If nothing is passed as an argument , an instance with 'default' as its name is created.Once you get an instance of the logger , its logging level can be set by calling the instance's `setLevel()` method.You just need to pass the desirable logging level as an argument to the `setLevel()` method.
+
+```javascript
+angular.module('test',['ui.logger']).run(['logger', function testRun(logger){
+  var logger_Instance=logger.getInstance('application_logger'); //application_logger will be set as name of the logger instance
+  logger_Instance.setLevel('debug');
+  try{
+    throw new TypeError('error ...!!!');
+  }catch(err){
+   logger_Instance.debug(err);
+  }
+}]);
+```
+
+
+**(3)** If a configuration needs to be done for all the logger instances, you can use provider of `logger` service i.e `loggerProvider`. One can set the logging level for all the instance using the `setLevel()` method of `loggerProvider`. Acceptable values of logger levels are 'debug','info','warn','log','error'. All the levels above your choosen logger level are automatically enabled. Say if you set 'info' as your debug level , it will automatically enable 'info','warn','log','warn' levels and disable 'debug' level. So if try to call debug() method with your instance, you will not get any results.
+
+```javascript
+angular.module('test',['ui.logger']).config(['loggerProvider', function(loggerProvider){
+  loggerProvider.setLevel('info');
+}]);
+angular.module('test',['ui.logger']).run(['logger', function testRun(logger){
+  var logger_Instance=logger.getInstance('application_logger');
+  try{
+    throw new TypeError('error ...!!!');
+  }catch(err){
+   logger_Instance.warn(err);
+   // "logger_Instance.debug(err);" using this statement will not give you any output.  
+  }
+}]);
+```
+
+
+
+**(4)** You can use,store or manipulate generated log data by defining a callback function which does the manipulations for you.Pass this callback function as an argument to the `setInterceptor()` method of the `loggerProvider`. This function will then get called everytime an exception occurs with the generated 'log data'.You can use this callback function to push the log data to a server. 
+
+```javascript
+angular.module('test',['ui.logger']).config(['loggerProvider', function(loggerProvider){
+  loggerProvider.setLevel('info');
+  loggerProvider.setInterceptor(function(data){
+    console.log(data);
+  });
+}]);
+angular.module('test',['ui.logger']).run(['logger', function testRun(logger){
+ var logger_Instance=logger.getInstance();
+  try{
+    throw new TypeError('error ...!!!');
+  }catch(err){
+   logger_Instance.info(err);
+  }
+}]);
+```
+
+
+**(5)** The logger instance by default writes the log data on the console and call the callback function(if specified). If you don't want to print the log data on the console , use `disableConsoleLogging()` method of `loggerProvider`. Pass 'true' as an argument to the method 
+to disable the console logging.If console logging is disabled only the callback function will be called everytime log data is generated for an exception.
+
+```javascript
+angular.module('test',['ui.logger']).config(['loggerProvider', function(loggerProvider){
+  loggerProvider.setLevel('info');
+  loggerProvider.setInterceptor(function(data){
+    console.log(data);
+  });
+  loggerProvider.disableConsoleLogging(true);
+}]);
+angular.module('test',['ui.logger']).run(['logger', function testRun(logger){
+ var logger_Instance=logger.getInstance();
+  try{
+    throw new TypeError('error ...!!!');
+  }catch(err){
+   logger_Instance.info(err);
+  }
+}]);
+```
+
+**(6)** You can have multiple instances of logger as well in a single angular application. Or even having a global instance for entire application and local instances for different services, controllers is also possible.
+
+```javascript
+angular.module('test',['ui.logger']).config(['loggerProvider', function(loggerProvider){
+  loggerProvider.setLevel('info');
+  loggerProvider.setInterceptor(function(data){
+    console.log(data);
+  });
+  loggerProvider.disableConsoleLogging(true);
+}]);
+angular.module('test',['ui.logger']).run(['logger','$rootScope', function testRun(logger,$rootScope){
+ $rootScope.loggerInstance=logger.getInstance('application_logger');
+  try{
+    throw new TypeError('error ...!!!');
+  }catch(err){
+   $rootScope.loggerInstance.info(err);
+  }
+}]);
+angular.module('test',['ui.logger']) .controller('TestCtrl', function ($scope,logger,$rootScope) {
+var loggerControllerInstance=logger.getInstance('controller_logger');
+loggerControllerInstance.info(loggerControllerInstance=== $rootScope.loggerInstance);
+try{
+    throw new TypeError(' new error ...!!!');
+  }catch(err){
+   $rootScope.loggerInstance.info(err);
+  }
+
+});
+
+```
 
 
 [![Analytics](https://ga-beacon.appspot.com/UA-71806888-3/ui-logger/)](https://github.com/angular-libs/ui-logger)
diff --git a/app/scripts/decorators/$log-decorator.js b/app/scripts/decorators/$log-decorator.js
index 97b84a2..55eef40 100644
--- a/app/scripts/decorators/$log-decorator.js
+++ b/app/scripts/decorators/$log-decorator.js
@@ -5,7 +5,8 @@
  * @name ui.logger.decorator:Log
  * @description
  * # Log
- * Decorator of the ui.logger
+ * Decorator for the angularJS $log (service for logging). The service decorator intercepts the
+ * creation of a $log service, allowing it to modify the behavior of the inbuilt service methods (log(),info(),warn(),error(),debug()).
  */
 angular.module('ui.logger')
   .config(function ($provide) {
diff --git a/app/scripts/services/StackTrace.js b/app/scripts/services/StackTrace.js
index 26eabee..bdd76a0 100644
--- a/app/scripts/services/StackTrace.js
+++ b/app/scripts/services/StackTrace.js
@@ -1,11 +1,23 @@
 'use strict';
 
+
 /**
  * @ngdoc service
- * @name ui.logger.StackTrace
+ * @name ui.logger.StackTraceProvider
+ * @description
+ * The service internally uses stacktrace.js,which uses browsers' Error.stack mechanism to generate stack traces, parses them,
+ * enhances them with source maps and uses Promises to return an Array of StackFrames. It basically serves as a wrapper for stacktrace.js and configures options required by the library.
+ */
+/**
+ * @ngdoc method
+ * @name SetOptions
+ * @methodOf ui.logger.StackTraceProvider
  * @description
- * # StackTrace
- * Service in the ui.logger.
+ * Configures options required by the library Stacktrace.js
+ * @param {object} opts Object which contains the options to be passed to the library
+ * @param {function} opts.filter  (optional) Function that takes StackFrame as argument and returns a boolean value .Only stack entries for which filter returns true are included then.Function(StackFrame => Boolean)
+ * @param {Object} opts.sourceCache (optional)Used to Pre-populate source cache to avoid network requests.SourceCache object should have key 'URL' with value as source for which StackFrames are required.(String URL => String Source)
+ * @param {Boolean} opts.offline (optional) Set to true to prevent all network requests (default: true)
  */
 (function(){
 
diff --git a/app/scripts/services/logger-levels.js b/app/scripts/services/logger-levels.js
index 5b05a9d..3890111 100644
--- a/app/scripts/services/logger-levels.js
+++ b/app/scripts/services/logger-levels.js
@@ -6,6 +6,22 @@
  * @description
  * # loggerLevels
  * Constant in the ui.logger.
+ * Used to specify various logging levels-
+ *
+ *
+ * 1) DEBUG -	Designates fine-grained informational events that are most useful to debug an application.Should be used write a debug message.
+ *
+ *
+ * 2) INFO	- Designates informational messages that highlight the progress of the application at coarse-grained level.Should be used write a information message.
+ *
+ *
+ * 3) WARN	- Designates potentially harmful situations.Should be used write a warning message.
+ *
+ *
+ * 4) LOG - Should be used write a log message.
+ *
+ *
+ * 5) ERROR - 	Designates error events that might still allow the application to continue running.Should be used write a error message.
  */
 angular.module('ui.logger')
   .constant('loggerLevels', ['debug','info','warn','log','error']);
diff --git a/app/scripts/services/logger-utils.js b/app/scripts/services/logger-utils.js
index 091e57f..934adae 100644
--- a/app/scripts/services/logger-utils.js
+++ b/app/scripts/services/logger-utils.js
@@ -2,11 +2,40 @@
 
 /**
  * @ngdoc service
- * @name ui.logger.loggerUtils
+ * @name ui.logger.logUtils
  * @description
  * # loggerUtils
  * Service in the ui.logger.
  */
+/**
+ * @ngdoc method
+ * @name $defaultLogger
+ * @methodOf ui.logger.logUtils
+ * @description
+ * Used to assign an instance of $log to service object, which can be used for console logging .
+ * @param {object} logger instance of logging service
+ * @returns {Object} returns logger instance
+ */
+/**
+ * @ngdoc method
+ * @name isEnabled
+ * @methodOf ui.logger.logUtils
+ * @description
+ * Checks if a particular logger level is enabled or not.
+ * @param {object} logger instance of logger.
+ * @param {string} type the logger level which is to checked
+ * @returns {Boolean} returns true if logger level is enabled
+ */
+/**
+ * @ngdoc method
+ * @name getLogData
+ * @methodOf ui.logger.logUtils
+ * @description
+ * Used to generate the log data corresponding to error or exceptions.
+ * @param {object} logger instance of logger.
+ * @param {object} exception the exception object corresponding to which log are to be generated
+ * @returns {Object} returns log information object containing name,time,url,message and stackframe corresponding to exception.
+ */
 angular.module('ui.logger')
   .service('logUtils', function (StackTrace, $window,loggerLevels,$injector,sourceMapUtil) {
     var $defaultLogger;
diff --git a/app/scripts/services/logger.js b/app/scripts/services/logger.js
index a301717..e311d99 100644
--- a/app/scripts/services/logger.js
+++ b/app/scripts/services/logger.js
@@ -5,8 +5,72 @@
  * @name ui.logger.logger
  * @description
  * # logger
- * Provider in the ui.logger.
+ * Used to provide the Logger instance.
  */
+
+/**
+ * @ngdoc service
+ * @name ui.logger.loggerProvider
+ * @description
+ * Used to do initial configuration for the logger Service.
+ */
+
+/**
+ * @ngdoc method
+ * @name SetLevel
+ * @methodOf ui.logger.loggerProvider
+ * @description
+ * Used to set the logger level
+ * @param {string} l name of the logging level to be configured. Acceptable values are - 'debug','info','warn','log','error'.
+ */
+
+/**
+ * @ngdoc method
+ * @name SetInterceptor
+ * @methodOf ui.logger.loggerProvider
+ * @description
+ * Used to set interceptor i.e. a callback function which will be called every time log data is generated.
+ * @param {function} cb callback function to be called every time log data is generated.
+ */
+
+/**
+ * @ngdoc method
+ * @name DisableConsoleLogging
+ * @methodOf ui.logger.loggerProvider
+ * @description
+ * Used to disable the writing of log data on console.
+ * @param {boolean} flag Used to enable or disable console logging.(default - false)
+ */
+
+/**
+ * @ngdoc method
+ * @name SetDefaultName
+ * @methodOf ui.logger.loggerProvider
+ * @description
+ * Used to set the default name for the logger instance.
+ * @param {String} name default name to be set for all the logger instances (default value - 'default')
+ */
+
+/**
+ * @ngdoc method
+ * @name getInstance
+ * @methodOf ui.logger.logger
+ * @description
+ * Used to get logger instance.
+ * @param {String} name name to be set for the logger instance(default value - 'default')
+
+ */
+/**
+ * @ngdoc method
+ * @name setLog
+ * @methodOf ui.logger.logger
+ * @description
+ * Used to assign an instance of $log to service object, which can be used for console logging if required by user .
+ * @param {object} $log instance of logging service.
+ */
+
+
+
 (function(){
   function SetLevel(l) {
     this.level=l;
diff --git a/app/scripts/services/source-map-util.js b/app/scripts/services/source-map-util.js
index 013ed40..6a160ad 100644
--- a/app/scripts/services/source-map-util.js
+++ b/app/scripts/services/source-map-util.js
@@ -1,12 +1,41 @@
 'use strict';
-
 /**
  * @ngdoc service
  * @name ui.logger.sourceMapUtil
  * @description
  * # sourceMapUtil
- * Factory in the ui.logger.
+ *  Factory in the ui.logger.
  */
+
+/**
+ * @ngdoc service
+ * @name ui.logger.sourceMapUtilProvider
+ * @description
+ * Used to do initial configuration for the sourceMapUtil Factory
+ */
+/**
+ * @ngdoc method
+ * @name configure
+ * @methodOf ui.logger.sourceMapUtilProvider
+ * @description
+ * Configures options required by the library source-map
+ * @param {object} options Object which contains the options to be passed to the library
+ * @param {Boolean} options.offline (optional) Set to true to prevent all network requests (default: true)
+ */
+/**
+ * @ngdoc method
+ * @name getOriginalLocation
+ * @methodOf ui.logger.sourceMapUtil
+ * @description
+ * Used to get original location and names of the function where exception occurred.(Helpful in case of minified files)
+ * @param {object} stack element of the stackFrame array generated for a particular exception.
+ * @param {String} stack.fileName name of the file in which error occured.
+ * @param {Number} stack.lineNumber lineNumber in which error occured.
+ * @param {Number} stack.columnNumber columnNumber in which error occured.
+ * @returns {Object} returns log information object containing original function name,line number,column number,source file name
+ * where the error occured.
+ */
+
 (function(){
   function findNode(nodeList,lineNumber,ColumnNumber){
     var first = 0;
@@ -176,7 +205,7 @@
                   $.ajax(sourceFileUlr).then(function(content) {
                     _cache[url]._file=content;
                     def1.resolve(true);
-                    _cache[url]._syntaxTree = window.esprima.parse(_cache[url]._file,{loc:true});
+                    _cache[url]._syntaxTree = window.esprima.parse(_cache[url]._file,{loc:true,range:true});
                     loc.name=_findFunctionName( _cache[url]._syntaxTree,loc.line, loc.column);
                     _stack=new window.StackFrame(loc.name, stack.args, loc.source, loc.line, loc.column);
                     def.resolve(_stack);
diff --git a/app/scripts/services/source-map.js b/app/scripts/services/source-map.js
index b0a4e5b..4005b58 100644
--- a/app/scripts/services/source-map.js
+++ b/app/scripts/services/source-map.js
@@ -5,6 +5,6 @@
  * @name ui.logger.sourceMap
  * @description
  * # sourceMap
- * Constant in the ui.logger.
+ * Used to access source-map library.The library is used to generate and consume the source map.
  */
 angular.module('ui.logger').constant('sourceMap', window.sourceMap);

From cbcbd8f0de8d4dd28560dcb901797c288197db12 Mon Sep 17 00:00:00 2001
From: kritika bahl <kritika.bahlnearbuy.com>
Date: Sun, 3 Apr 2016 17:43:17 +0530
Subject: [PATCH 2/2] documentation

---
 app/scripts/services/source-map-util.js | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/app/scripts/services/source-map-util.js b/app/scripts/services/source-map-util.js
index 6a160ad..83ede45 100644
--- a/app/scripts/services/source-map-util.js
+++ b/app/scripts/services/source-map-util.js
@@ -205,7 +205,7 @@
                   $.ajax(sourceFileUlr).then(function(content) {
                     _cache[url]._file=content;
                     def1.resolve(true);
-                    _cache[url]._syntaxTree = window.esprima.parse(_cache[url]._file,{loc:true,range:true});
+                    _cache[url]._syntaxTree = window.esprima.parse(_cache[url]._file,{loc:true});
                     loc.name=_findFunctionName( _cache[url]._syntaxTree,loc.line, loc.column);
                     _stack=new window.StackFrame(loc.name, stack.args, loc.source, loc.line, loc.column);
                     def.resolve(_stack);