fixing documentation

Author: totorean

app/components/location/locationDirective.js

@@ -1,3 +1,12 @@
+/**
+ * @ngdoc directive
+ * @name location
+ * @plm
+ *
+ * @description
+ * A directive for rendering an icon with label underneath and a tooltip
+ *
+ */
 Components.directive('location', function () {
     return {
         restrict: 'E', //E = element, A = attribute, C = class, M = comment   

app/components/skycon/skyconDirective.js

@@ -1,3 +1,10 @@
+/**
+ * @ngdoc directive
+ * @name skycon
+ *
+ * @description
+ * A directive for rendering an icon from skycons
+ */
 Components.directive('skycon', function () {
     return {
         restrict: 'E', //E = element, A = attribute, C = class, M = comment   

app/forecast/forecast.js

@@ -1,3 +1,10 @@
+/**
+ * @ngdoc controller
+ * @name ForecastCtrl
+ *
+ * @description
+ * A controller that loads the data for a location making it available for the view
+ */
 'use strict';
 
 angular.module('darkskyForecast.forecast', ['ngRoute'])

app/main/locationsService.js

@@ -1,7 +1,23 @@
+/**
+ * @ngdoc service
+ * @name locationsService
+ *
+ * @description
+ * A service used for fetching the list of available locations from a .json file.
+ * Might later be used to fetch the list from a server.
+ */
 'use strict';
 
 angular.module('darkskyForecast.main')
     .service('locationsService', function ($q, $http) {
+
+        /**
+         * @ngdoc function
+         * @name getLocations
+         *
+         * @returns {Array} list of locations
+         *
+         */
         this.getLocations = function () {
             var deferred = $q.defer();
 

app/main/main.js

@@ -1,3 +1,11 @@
+/**
+ * @ngdoc controller
+ * @name MainCtrl
+ *
+ * @description
+ * A controller for fetching the coordinates and the current
+ * weather for a selected location and storing them in the local storage
+ */
 'use strict';
 
 angular.module('darkskyForecast.main', ['ngRoute'])
@@ -17,6 +25,15 @@ angular.module('darkskyForecast.main', ['ngRoute'])
                 $scope.locations = locations;
             })
 
+        /**
+         * @ngdoc function
+         * @name displayWeather
+         * @description A function that fetches the coordinates and the current weather for a 
+         * selected location and stores them in the local storage
+         *
+         * @param {Number} index the clicked location index
+         *
+         */
         $scope.displayWeather = function (index) {
             var locationDetails = $scope.locations[index];
             var location = locationDetails.id;

app/services/coordinatesService.js

@@ -1,31 +1,53 @@
+/**
+ * @ngdoc overview 
+ * @name service.coordService
+ */
 'use strict';
 
 angular.module('service.coordService', [])
-    .service('coordService', function ($q, $http, GOOGLE_API) {
-        this.getCoords = function (location) {
-            var deferred = $q.defer();
 
-            $http({
-                    method: 'GET',
-                    timeout: 300000,
-                    url: GOOGLE_API.URL,
-                    params: {
-                        'address': location,
-                        'key': GOOGLE_API.KEY
-                    }
-                })
-                .then(function (data) {
-                    if (parseInt(data.status) === 200) {
-                        deferred.resolve(data.data.results[0].geometry.location);
-                    } else {
-                        deferred.reject(data.status);
-                    }
+/**
+ * @ngdoc method
+ * @methodOf service.coordService.coordService
+ * @name coordService
+ *
+ * @description
+ * A service used for fetching the coordinates of a location via http.
+ */
+.service('coordService', function ($q, $http, GOOGLE_API) {
 
-                })
-                .catch(function (data) {
-                    deferred.reject(data.error_message);
-                });
+    /**
+     * @ngdoc function
+     * @name getCoords
+     *
+     * @param {String} location the location name
+     * @returns {Object} object containing the latitude and longitude
+     *
+     */
+    this.getCoords = function (location) {
+        var deferred = $q.defer();
 
-            return deferred.promise;
-        }
-    });
+        $http({
+                method: 'GET',
+                timeout: 300000,
+                url: GOOGLE_API.URL,
+                params: {
+                    'address': location,
+                    'key': GOOGLE_API.KEY
+                }
+            })
+            .then(function (data) {
+                if (parseInt(data.status) === 200) {
+                    deferred.resolve(data.data.results[0].geometry.location);
+                } else {
+                    deferred.reject(data.status);
+                }
+
+            })
+            .catch(function (data) {
+                deferred.reject(data.error_message);
+            });
+
+        return deferred.promise;
+    }
+});

app/services/forecastService.js

@@ -1,8 +1,23 @@
+/**
+ * @ngdoc function
+ * @name forecastService
+ *
+ * @description
+ * A service used for fetching the current weather data via http.
+ */
 'use strict';
 
 angular.module('service.forecastService', [])
     .service('forecastService', function ($q, $http, $sce, DARKSKY_API) {
 
+        /**
+         * @ngdoc function
+         * @name getWeather
+         *
+         * @param {Object} coords an object with lat (latitude) and lng (longitude) parameters
+         * @returns {Object} object containing current weather data
+         *
+         */
         this.getWeather = function (coords) {
             var deferred = $q.defer();