From 5a53984b43e8ecfa065139e80d4f5efcdc6b0074 Mon Sep 17 00:00:00 2001
From: bjarnef <bjarne_fyrstenborg@hotmail.com>
Date: Tue, 21 Jun 2016 01:25:14 +0200
Subject: [PATCH] Document localizationService and localize directive

---
 .../localization/localize.directive.js        | 14 ++++++
 .../common/services/localization.service.js   | 47 ++++++++++++++++++-
 2 files changed, 59 insertions(+), 2 deletions(-)

diff --git a/src/Umbraco.Web.UI.Client/src/common/directives/components/localization/localize.directive.js b/src/Umbraco.Web.UI.Client/src/common/directives/components/localization/localize.directive.js
index 52271961a7..ca5b3c0f65 100644
--- a/src/Umbraco.Web.UI.Client/src/common/directives/components/localization/localize.directive.js
+++ b/src/Umbraco.Web.UI.Client/src/common/directives/components/localization/localize.directive.js
@@ -1,5 +1,12 @@
 angular.module("umbraco.directives")
 
+    /**
+    * @ngdoc directive
+    * @name umbraco.directives.directive:localize
+    * @restrict E
+    * @function
+    * @description Localize element directive
+    **/
     .directive('localize', function ($log, localizationService) {
         return {
             restrict: 'E',
@@ -17,6 +24,13 @@ angular.module("umbraco.directives")
         };
     })
 
+    /**
+    * @ngdoc directive
+    * @name umbraco.directives.directive:localize
+    * @restrict A
+    * @function
+    * @description Localize attribute directive
+    **/
     .directive('localize', function ($log, localizationService) {
         return {
             restrict: 'A',
diff --git a/src/Umbraco.Web.UI.Client/src/common/services/localization.service.js b/src/Umbraco.Web.UI.Client/src/common/services/localization.service.js
index 7cfc79a083..430ed02242 100644
--- a/src/Umbraco.Web.UI.Client/src/common/services/localization.service.js
+++ b/src/Umbraco.Web.UI.Client/src/common/services/localization.service.js
@@ -1,3 +1,26 @@
+/**
+ * @ngdoc service
+ * @name umbraco.services.localizationService
+ *
+ * @requires $http
+ * @requires $q
+ * @requires $window
+ * @requires $filter
+ *
+ * @description
+ * Application-wide service for handling localization
+ *
+ * ##usage
+ * To use, simply inject the localizationService into any controller that needs it, and make
+ * sure the umbraco.services module is accesible - which it should be by default.
+ *
+ * <pre>
+ *    localizationService.localize("area_key").then(function(value){
+ *        element.html(value);
+ *    });
+ * </pre>
+ */
+
 angular.module('umbraco.services')
 .factory('localizationService', function ($http, $q, eventsService, $window, $filter, userService) {
 
@@ -78,7 +101,17 @@ angular.module('umbraco.services')
             return deferred.promise;
         },
 
-        //helper to tokenize and compile a localization string
+        /**
+         * @ngdoc method
+         * @name umbraco.services.localizationService#tokenize
+         * @methodOf umbraco.services.localizationService
+         *
+         * @description
+         * Helper to tokenize and compile a localization string
+         * @param {String} value the value to tokenize
+         * @param {Object} scope the $scope object 
+         * @returns {String} tokenized resource string
+         */
         tokenize: function (value, scope) {
             if (value) {
                 var localizer = value.split(':');
@@ -95,7 +128,17 @@ angular.module('umbraco.services')
             return value;
         },
 
-        // checks the dictionary for a localized resource string
+        /**
+         * @ngdoc method
+         * @name umbraco.services.localizationService#localize
+         * @methodOf umbraco.services.localizationService
+         *
+         * @description
+         * Checks the dictionary for a localized resource string
+         * @param {String} value the area/key to localize
+         * @param {Array} tokens if specified this array will be sent as parameter values 
+         * @returns {String} localized resource string
+         */
         localize: function (value, tokens) {
             return service.initLocalizedResources().then(function (dic) {
                 var val = _lookup(value, tokens, dic);