Documentation

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'
   ]);
 

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)

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) {

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(){
 

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']);

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;

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;