From bdf6de3a1df8fc77ce9dd5f9e4daee6db58be37e Mon Sep 17 00:00:00 2001 From: Dylan Price Date: Wed, 7 Aug 2013 19:25:24 -0700 Subject: [PATCH] Switched documentation to docular. --- Gruntfile.js | 30 +++-- package.json | 3 +- src/directives/gmInfoWindow.js | 40 +++--- src/directives/gmMap.js | 85 +++++++------ src/directives/gmMarkers.js | 187 +++++++++++++++-------------- src/module.js | 45 ++++--- src/services/angulargmContainer.js | 14 +-- src/services/angulargmUtils.js | 43 +++++-- 8 files changed, 256 insertions(+), 191 deletions(-) diff --git a/Gruntfile.js b/Gruntfile.js index 64bdc6a..0b04b37 100644 --- a/Gruntfile.js +++ b/Gruntfile.js @@ -6,7 +6,7 @@ module.exports = function(grunt) { grunt.loadNpmTasks('grunt-contrib-concat'); grunt.loadNpmTasks('grunt-contrib-uglify'); grunt.loadNpmTasks('grunt-karma'); - grunt.loadNpmTasks('grunt-jsdoc'); + grunt.loadNpmTasks('grunt-docular'); // Project configuration. grunt.initConfig({ @@ -79,20 +79,30 @@ module.exports = function(grunt) { browsers: ['PhantomJS'] } }, - jsdoc : { - compile: { - src: ['README.md', '<%= dirs.src %>'], - options: { - destination: '<%= dirs.dest %>/docs', - configure: 'jsdoc/conf.json', - template: 'jsdoc/template' + docular : { + groups: [ + { + groupTitle: 'AngularGM Docs', + groupId: 'angulargm', + groupIcon: 'icon-map-marker', + sections: [ + { + id: "api", + title: "AngularGM API", + scripts: [ + "src/", + ] + } + ] } - } + ], + showDocularDocs: false, + showAngularDocs: false } }); grunt.registerTask('default', ['build']); - grunt.registerTask('build', ['jshint', 'karma:unit', 'concat', 'uglify', 'jsdoc']); + grunt.registerTask('build', ['jshint', 'karma:unit', 'concat', 'uglify', 'docular']); }; diff --git a/package.json b/package.json index bf1332e..e9d7ec3 100644 --- a/package.json +++ b/package.json @@ -29,6 +29,7 @@ "karma-requirejs": "~0.1.0", "karma-coffee-preprocessor": "~0.1.0", "karma": "~0.10.1", - "karma-coverage": "~0.1.0" + "karma-coverage": "~0.1.0", + "grunt-docular": "~0.1.1" } } diff --git a/src/directives/gmInfoWindow.js b/src/directives/gmInfoWindow.js index dee7e38..a52f481 100644 --- a/src/directives/gmInfoWindow.js +++ b/src/directives/gmInfoWindow.js @@ -1,29 +1,31 @@ 'use strict'; /** + * @ngdoc directive + * @name angulargm.directive:gmInfoWindow + * @element ANY + * + * @description * A directive for creating a google.maps.InfoWindow. * - * Usage: - * ```html - *
- *
- * ``` - * - * + `gm-info-window`: name of scope variable to store the - * google.maps.InfoWindow in. Does not have to already exist. + * + @param {string} gm-info-window name of scope variable to store the + * [google.maps.InfoWindow](https://developers.google.com/maps/documentation/javascript/reference#InfoWindow) + * in. Does not have to already exist. * - * + `gm-info-window-options`: object in the current scope that is a - * google.maps.InfoWindowOptions object. If unspecified, google maps api - * defaults will be used. + * + @param {expression} gm-info-window-options object in the current scope + * that is a + * [google.maps.InfoWindowOptions](https://developers.google.com/maps/documentation/javascript/reference#InfoWindowOptions) + * object. If unspecified, google maps api defaults will be used. * - * + `gm-on-*event*`: an angular expression which evaluates to an event - * handler. This handler will be attached to the InfoWindow's \*event\* - * event. The variable 'infoWindow' evaluates to the InfoWindow. For - * example: `gm-on-closeclick="myCloseclickFn(infoWindow)"` will call your - * myCloseclickFn whenever the InfoWindow is clicked closed. You may have - * multiple `gm-on-*event*` handlers, but only one for each type of event. + * + @param {expression} gm-on-*event* an angular expression which evaluates to an + * event handler. This handler will be attached to the InfoWindow's \*event\* + * event. The variable `infoWindow` evaluates to the InfoWindow. For example: + * ```html + * gm-on-closeclick="myCloseclickFn(infoWindow)" + * ``` + * will call your myCloseclickFn whenever the InfoWindow is clicked closed. You + * may have multiple `gm-on-*event*` handlers, but only one for each type of + * event. * * @module gmInfoWindow */ diff --git a/src/directives/gmMap.js b/src/directives/gmMap.js index 16dd9d0..3ba51a2 100644 --- a/src/directives/gmMap.js +++ b/src/directives/gmMap.js @@ -1,65 +1,64 @@ 'use strict'; /** + * @ngdoc directive + * @name angulargm.directive:gmMap + * @element ANY + * + * @description * A directive for embedding google maps into your app. * - * Usage: - * ```html - * - * - * ``` + * `gm-map-id` is required. The `gm-center`, `gm-zoom`, `gm-bounds`, and + * `gm-map-type-id` variables do not have to exist in the current scope--they + * will be created if necessary. All three have bi-directional association, + * i.e. drag or zoom the map and they will update, update them and the map + * will change. However, any initial state of these three variables will be + * ignored. * - * + `gm-map-id`: angular expression that evaluates to a unique string id for - * the map, e.g. "'map_canvas'" or "myMapId" where myMapId is a variable in - * the current scope. This allows you to have multiple maps/instances of the - * directive. + * If you need to get a handle on the google.maps.Map object, see + * [angulargmContainer] * - * + `gm-center`: name for a center variable in the current scope. The value - * will be a google.maps.LatLng object. + * @param {expression} gm-map-id angular expression that evaluates to a unique + * string id for the map, e.g. `'map_canvas'` or `myMapId` where myMapId is a + * variable in the current scope. This allows you to have multiple + * maps/instances of the directive. * - * + `gm-zoom`: name for a zoom variable in the current scope. Value will be - * an integer. * - * + `gm-bounds`: name for a bounds variable in the current scope. Value will - * be a google.maps.LatLngBounds object. + * @param {string} gm-center name for a center variable in the current scope. + * The value will be a google.maps.LatLng object. * - * + `gm-map-type-id`: name for a mapTypeId variable in the current scope. - * Value will be a string. * - * + `gm-map-options`: object in the current scope that is a - * google.maps.MapOptions object. If unspecified, will use the values in - * angulargmDefaults.mapOptions. [angulargmDefaults]{@link module:angulargmDefaults} - * is a service, so it is both injectable and overrideable (using - * $provide.decorator). + * @param {string} gm-zoom name for a zoom variable in the current scope. + * Value will be an integer. * - * All attributes except `gm-map-options` are required. The `gm-center`, - * `gm-zoom`, `gm-bounds`, and `gm-map-type-id` variables do not have to exist in - * the current scope--they will be created if necessary. All three have - * bi-directional association, i.e. drag or zoom the map and they will update, - * update them and the map will change. However, any initial state of these - * three variables will be ignored. * - * If you need to get a handle on the google.maps.Map object, see - * [angulargmContainer]{@link module:angulargmContainer} + * @param {string} gm-bounds name for a bounds variable in the current scope. + * Value will be a google.maps.LatLngBounds object. * - * Events: * - * + `gmMapResize`: google.maps.event.trigger(map, 'resize') To use: - * `$scope.$broadcast('gmMapResize', 'myMapId')` + * @param {string} gm-map-type-id name for a mapTypeId variable in the current + * scope. Value will be a string. * - * Parameters: * - * + `mapId`: required. The id of your map. This is what you set - * `gm-map-id` to. It is necessary because there may be multiple - * instances of the `gmMap` directive. + * @param {expression} gm-map-options object in the current scope that is a + * google.maps.MapOptions object. If unspecified, will use the values in + * angulargmDefaults.mapOptions. [angulargmDefaults] is a service, so it is + * both injectable and overrideable (using $provide.decorator). * - * @module gmMap */ + +/** + * @ngdoc event + * @name angulargm.directive:gmMap#gmMapResize + * @eventOf angulargm.directive:gmMap + * @eventType listen on current gmMap scope + * @param {string} mapId Required. The id of your map. + * @example + * ```js + * $scope.$broadcast('gmMapResize', 'myMapId') + * ``` + */ + (function () { angular.module('AngularGM'). diff --git a/src/directives/gmMarkers.js b/src/directives/gmMarkers.js index 3a454ca..03e763a 100644 --- a/src/directives/gmMarkers.js +++ b/src/directives/gmMarkers.js @@ -1,6 +1,11 @@ 'use strict'; /** + * @ngdoc directive + * @name angulargm.directive:gmMarkers + * @element ANY + * + * @description * A directive for adding markers to a `gmMap`. You may have multiple per `gmMap`. * * To use, you specify an array of custom objects and tell the directive how to @@ -8,106 +13,114 @@ * objects. If you assign a new array to your scope variable or change the * array's length, the markers will also update. * - * Usage: - * ```html - * - * - * - * - * ``` - * - * + `gm-objects`: an array of objects in the current scope. These can be any - * objects you wish to attach to markers, the only requirement is that they - * have a uniform method of accessing a lat and lng. - * - * + `gm-get-lat-lng`: an angular expression that given an object from - * `gm-objects`, evaluates to an object with lat and lng properties. Your - * object can be accessed through the variable 'object'. For example, if - * your controller has - * ``` - * ... - * $scope.myObjects = [ - * { id: 0, location: { lat: 5, lng: 5} }, - * { id: 1, location: { lat: 6, lng: 6} } - * ] - * ... - * ``` - * then in the `gm-markers` directive you would put - * ``` - * ... - * gm-objects="myObjects" - * gm-get-lat-lng="{ lat: object.location.lat, lng: object.location.lng }" - * ... - * ``` + * Only the `gm-objects` and `gm-get-lat-lng` attributes are required. * - * + `gm-get-marker-options`: an angular expression that given an object from - * `gm-objects`, evaluates to a google.maps.MarkerOptions object. Your object - * can be accessed through the variable 'object'. If unspecified, google maps - * api defaults will be used. + * @param {expression} gm-objects an array of objects in the current scope. + * These can be any objects you wish to attach to markers, the only requirement + * is that they have a uniform method of accessing a lat and lng. * - * + `gm-events`: a variable in the current scope that is used to simulate - * events on markers. Setting this variable to an object of the form - * ``` - * [ - * { - * event: 'click', - * locations: [new google.maps.LatLng(45, -120), ...] - * }, - * ... - * ] - * ``` - * will generate the named events on the markers at the given locations, if a - * marker at each location exists. Note: when setting the `gm-events` - * variable, you must set it to a new object for the changes to be detected. - * Code like `myEvent[0]["locations"] = [new google.maps.LatLng(45,-120)]` - * will not work. - * * - * + `gm-on-*event*`: an angular expression which evaluates to an event - * handler. This handler will be attached to each marker's \*event\* event. - * The variables 'object' and 'marker' evaluate to your object and the - * google.maps.Marker, respectively. For example: - * `gm-on-click="myClickFn(object, marker)"` will call your myClickFn - * whenever a marker is clicked. You may have multiple `gm-on-*event*` - * handlers, but only one for each type of event. + * @param {expression} gm-get-lat-lng an angular expression that given an object from + * `gm-objects`, evaluates to an object with lat and lng properties. Your + * object can be accessed through the variable `object`. For example, if + * your controller has + * ```js + * ... + * $scope.myObjects = [ + * { id: 0, location: { lat: 5, lng: 5} }, + * { id: 1, location: { lat: 6, lng: 6} } + * ] + * ... + * ``` + * then in the `gm-markers` directive you would put + * ```js + * ... + * gm-objects="myObjects" + * gm-get-lat-lng="{ lat: object.location.lat, lng: object.location.lng }" + * ... + * ``` * + * @param {expression} gm-get-marker-options an angular expression that given + * an object from `gm-objects`, evaluates to a + * [google.maps.MarkerOptions](https://developers.google.com/maps/documentation/javascript/reference#MarkerOptions) + * object. Your object can be accessed through the variable `object`. If + * unspecified, google maps api defaults will be used. * - * Only the `gm-objects` and `gm-get-lat-lng` attributes are required. * - * Events: + * @param {string} gm-events a variable in the current scope that is used to + * simulate events on markers. Setting this variable to an object of the form + * ```js + * [ + * { + * event: 'click', + * locations: [new google.maps.LatLng(45, -120), ...] + * }, + * ... + * ] + * ``` + * will generate the named events on the markers at the given locations, if a + * marker at each location exists. Note: when setting the `gm-events` variable, + * you must set it to a new object for the changes to be detected. Code like + * ```js + * myEvent[0]["locations"] = [new google.maps.LatLng(45,-120)] + * ``` + * will not work. + * * - * + `gmMarkersRedraw`: force the gmMarkers directive to clear and redraw all - * markers. To use: `$scope.$broadcast('gmMarkersRedraw', 'myObjects')` + * @param {expression} gm-on-*event* an angular expression which evaluates to + * an event handler. This handler will be attached to each marker's \*event\* + * event. The variables 'object' and 'marker' evaluate to your object and the + * [google.maps.Marker](https://developers.google.com/maps/documentation/javascript/reference#Marker), + * respectively. For example: + * ```html + * gm-on-click="myClickFn(object, marker)" + * ``` + * will call your `myClickFn` whenever a marker is clicked. You may have + * multiple `gm-on-*event*` handlers, but only one for each type of event. + */ + +/** + * @ngdoc event + * @name angulargm.directive:gmMarkers#gmMarkersRedraw + * @eventOf angulargm.directive:gmMarkers + * @eventType listen on current gmMarkers scope * - * Parameters: + * @description Force the gmMarkers directive to clear and redraw all markers. * - * + `objects`: Not required. The name of the scope variable which holds - * the objects to redraw markers for, i.e. what you set `gm-objects` to. - * It is useful because there may be multiple instances of the - * `gmMarkers` directive. If not specified, all instances of gmMarkers - * which are child scopes will redraw their markers. + * @param {string} objects Not required. The name of the scope variable which + * holds the objects to redraw markers for, i.e. what you set `gm-objects` to. + * It is useful because there may be multiple instances of the `gmMarkers` + * directive. If not specified, all instances of gmMarkers which are child + * scopes will redraw their markers. * - * + `gmMarkersUpdated`: emitted when markers are updated. To use: - * ``` - * $scope.$on('gmMarkersUpdated', function(event, objects) { - * if (objects === 'myObjects') { - * ... - * } - * }); - * ``` + * @example + * ```js + * $scope.$broadcast('gmMarkersRedraw', 'myObjects'); + * ``` + */ + +/** + * @ngdoc event + * @name angulargm.directive:gmMarkers#gmMarkersUpdated + * @eventOf angulargm.directive:gmMarkers + * @eventType emit on current gmMarkers scope + * + * @description Emitted when markers are updated. * - * Parameters: - * - * + `objects`: the name of the scope variable which holds the objects the - * gmMarkers directive was constructed with. This is what `gm-objects` - * was set to. + * @param {string} objects the name of the scope variable which holds the + * objects the gmMarkers directive was constructed with. This is what + * `gm-objects` was set to. * - * @module gmMarkers + * @example + * ```js + * $scope.$on('gmMarkersUpdated', function(event, objects) { + * if (objects === 'myObjects') { + * ... + * } + * }); + * ``` */ + (function () { angular.module('AngularGM'). diff --git a/src/module.js b/src/module.js index 8fc680f..d2ccab1 100644 --- a/src/module.js +++ b/src/module.js @@ -1,40 +1,57 @@ 'use strict'; /** + * @doc module + * @name angulargm + * + * @description * Module for embedding Google Maps into AngularJS applications. * - * ## API Documentation + * + * # API Documentation * See... * - * + {@link module:gmMap} for usage of the `` directive - * + {@link module:gmMarkers} for usage of the `` directive - * + {@link module:gmInfoWindow} for usage of the `
* * - * (JSDoc is escaping my iframe so for the time being just click the link.) - * - * @module AngularGM * @author Dylan Price */ (function() { angular.module('AngularGM', []). /** + * @ngdoc service + * @name angulargm.service:angulargmDefaults + * + * @description * Default configuration. * * To provide your own default config, use the following - * ``` + * ```js * angular.module('myModule').config(function($provide) { * $provide.decorator('angulargmDefaults', function($delegate) { * return angular.extend($delegate, { - * // Note: markerConstructor must implement getPosition() and setMap() - * // like google.maps.Marker * 'markerConstructor': myCustomMarkerConstructor, * 'mapOptions': { * center: new google.maps.LatLng(55, 111), @@ -45,8 +62,6 @@ * }); * }); * ``` - * - * @module angulargmDefaults */ value('angulargmDefaults', { 'markerConstructor': google.maps.Marker, diff --git a/src/services/angulargmContainer.js b/src/services/angulargmContainer.js index 8df018e..d5b6708 100644 --- a/src/services/angulargmContainer.js +++ b/src/services/angulargmContainer.js @@ -1,13 +1,17 @@ 'use strict'; /** + * @ngdoc service + * @name angulargm.service:angulargmContainer + * + * @description * A container which maps mapIds to google.maps.Map instances, and additionally * allows getting a promise of a map for custom configuration of the map. * - * If you want a handle to the map, you should use the getMapPromise(mapId) + * If you want a handle to the map, you should use the `getMapPromise(mapId)` * method so you can guarantee the map will be initialized. For example, * - * ``` + * ```js * angular.module('myModule'). * * run(function(angulargmContainer) { @@ -18,8 +22,6 @@ * }); * }); * ``` - * - * @module angulargmContainer */ (function () { angular.module('AngularGM'). @@ -34,7 +36,6 @@ * @param {google.maps.Map} map the google map * @throw if there is already a map with mapId, or if map is not a * google.maps.Map - * @method */ function addMap(mapId, map) { if (!(map instanceof google.maps.Map)) { @@ -53,7 +54,6 @@ * @param {string} mapId the unique id of the map * @return {google.maps.Map|undefined} the map, or undefined if there is no * map for mapId - * @method */ function getMap(mapId) { return maps[mapId]; @@ -65,7 +65,6 @@ * been created yet * @return {angular.q.promise} a promise of a map that will be resolved * when the map is added - * @method */ function getMapPromise(mapId) { var defer = defers[mapId] || $q.defer(); @@ -80,7 +79,6 @@ * http://stackoverflow.com/questions/10485582/what-is-the-proper-way-to-destroy-a-map-instance * * @param {string} mapId the unique id of the map to remove - * @method */ function removeMap(mapId) { if (mapId in maps) { diff --git a/src/services/angulargmUtils.js b/src/services/angulargmUtils.js index 03b4de1..d375d22 100644 --- a/src/services/angulargmUtils.js +++ b/src/services/angulargmUtils.js @@ -1,6 +1,10 @@ 'use strict'; /** + * @ngdoc service + * @name angulargm.service:angulargmUtils + * + * @description * Common utility functions. */ (function () { @@ -10,15 +14,22 @@ /** * Check if two floating point numbers are equal. - * @return true if f1 and f2 are 'very close' + * + * @param {number} f1 first number + * @param {number} f2 second number + * @return {boolean} true if f1 and f2 are 'very close' (within 0.000001) */ function floatEqual (f1, f2) { return (Math.abs(f1 - f2) < 0.000001); } /** - * @param {google.maps.LatLng} l1 - * @param {google.maps.LatLng} l2 + * @ngdoc function + * @name #latLngEqual + * @methodOf angulargm.service:angulargmUtils + * + * @param {google.maps.LatLng} l1 first + * @param {google.maps.LatLng} l2 second * @return {boolean} true if l1 and l2 are 'very close'. If either are null * or not google.maps.LatLng objects returns false. */ @@ -31,8 +42,12 @@ } /** - * @param {google.maps.LatLngBounds} b1 - * @param {google.maps.LatLngBounds} b2 + * @ngdoc function + * @name #boundsEqual + * @methodOf angulargm.service:angulargmUtils + * + * @param {google.maps.LatLngBounds} b1 first + * @param {google.maps.LatLngBounds} b2 second * @return {boolean} true if b1 and b2 are 'very close'. If either are null * or not google.maps.LatLngBounds objects returns false. */ @@ -50,7 +65,11 @@ } /** - * @param {google.maps.LatLng} latLng + * @ngdoc function + * @name #latLngToObj + * @methodOf angulargm.service:angulargmUtils + * + * @param {google.maps.LatLng} latLng the LatLng * @return {Object} object literal with 'lat' and 'lng' properties. * @throw if latLng not instanceof google.maps.LatLng */ @@ -65,6 +84,10 @@ } /** + * @ngdoc function + * @name #objToLatLng + * @methodOf angulargm.service:angulargmUtils + * * @param {Object} obj of the form { lat: 40, lng: -120 } * @return {google.maps.LatLng} returns null if problems with obj (null, * NaN, etc.) @@ -83,8 +106,12 @@ } /** - * @param {google.maps.LatLng} latLng - * @return true if either lat or lng of latLng is null or isNaN + * @ngdoc function + * @name #hasNaN + * @methodOf angulargm.service:angulargmUtils + * + * @param {google.maps.LatLng} latLng the LatLng + * @return {boolean} true if either lat or lng of latLng is null or isNaN */ function hasNaN(latLng) { if (!(latLng instanceof google.maps.LatLng))