From 4b46cf9a422c308272b1fbcef0fcccaa4752f410 Mon Sep 17 00:00:00 2001 From: warrenbuckley Date: Tue, 26 Aug 2014 14:54:37 +0100 Subject: [PATCH 1/3] Update .gitignore for output files generated by ng-docs --- .gitignore | 3 +++ 1 file changed, 3 insertions(+) diff --git a/.gitignore b/.gitignore index 64d8ca9cd0..7ee06c2c7f 100644 --- a/.gitignore +++ b/.gitignore @@ -117,3 +117,6 @@ build/ApiDocs/* build/ApiDocs/Output/* src/Umbraco.Web.UI.Client/bower_components/* /src/Umbraco.Web.UI/Umbraco/preview + +#Ignore Rule for output of generated documentation files from Grunt docserve +src/Umbraco.Web.UI.Client/docs/api \ No newline at end of file From 9784a3d8686ecca09fea61ab1cba179b0a35db3a Mon Sep 17 00:00:00 2001 From: warrenbuckley Date: Tue, 26 Aug 2014 15:07:40 +0100 Subject: [PATCH 2/3] Add new Grunt Task 'docserve' to rerun ng-docs task & spin up a test server to browse to along with new watch task to recompile generated docs --- src/Umbraco.Web.UI.Client/gruntFile.js | 27 +++++++++++++++++++++++++- 1 file changed, 26 insertions(+), 1 deletion(-) diff --git a/src/Umbraco.Web.UI.Client/gruntFile.js b/src/Umbraco.Web.UI.Client/gruntFile.js index aceb2f9be6..a201d6d88c 100644 --- a/src/Umbraco.Web.UI.Client/gruntFile.js +++ b/src/Umbraco.Web.UI.Client/gruntFile.js @@ -4,6 +4,7 @@ module.exports = function (grunt) { // Default task. grunt.registerTask('default', ['jshint:dev','build','karma:unit']); grunt.registerTask('dev', ['jshint:dev', 'build-dev', 'webserver', 'open:dev', 'watch']); + grunt.registerTask('docserve', ['docs:api', 'connect:docserver', 'open:docs', 'watch:docs']); grunt.registerTask('vs', ['jshint:dev', 'build-dev', 'watch']); //TODO: Too much watching, this brings windows to it's knees when in dev mode @@ -75,12 +76,31 @@ module.exports = function (grunt) { } } }, - testserver: {} + testserver: {}, + docserver: { + options: { + port: 8880, + hostname: '0.0.0.0', + base: './docs/api', + middleware: function(connect, options){ + return [ + //uncomment to enable CSP + // util.csp(), + //util.rewrite(), + connect.static(options.base), + connect.directory(options.base) + ]; + } + } + }, }, open : { dev : { path: 'http://localhost:9990/belle/' + }, + docs : { + path: 'http://localhost:8880/index.html' } }, @@ -357,6 +377,11 @@ module.exports = function (grunt) { packages: { files: 'src/packages/**/*.*', tasks: ['watch-packages', 'timestamp'], + }, + + docs: { + files: ['src/**/*.js', 'src/*.js'], + tasks: ['docs:api'], } }, From 29afebdb60a57a64be219fe9d1a35b45a94c5efc Mon Sep 17 00:00:00 2001 From: warrenbuckley Date: Tue, 26 Aug 2014 15:08:40 +0100 Subject: [PATCH 3/3] Initial starting work on ng-doc fleshing out for auth.resource.js (Also to see if Core team happy with this before investing too much time) --- .../src/common/resources/auth.resource.js | 113 ++++++++++++++++-- 1 file changed, 103 insertions(+), 10 deletions(-) diff --git a/src/Umbraco.Web.UI.Client/src/common/resources/auth.resource.js b/src/Umbraco.Web.UI.Client/src/common/resources/auth.resource.js index 7f214400d5..e83b35e087 100644 --- a/src/Umbraco.Web.UI.Client/src/common/resources/auth.resource.js +++ b/src/Umbraco.Web.UI.Client/src/common/resources/auth.resource.js @@ -1,14 +1,38 @@ /** - * @ngdoc service - * @name umbraco.resources.authResource - * @description Loads in data for authentication -**/ + * @ngdoc service + * @name umbraco.resources.authResource + * @description + * This Resource perfomrs actions to common authentication tasks for the Umbraco backoffice user + * + * @requires $q + * @requires $http + * @requires umbRequestHelper + * @requires angularHelper + */ function authResource($q, $http, umbRequestHelper, angularHelper) { return { - //currentUser: currentUser, - /** Logs the user in if the credentials are good */ + /** + * @ngdoc method + * @name umbraco.resources.authResource#performLogin + * @methodOf umbraco.resources.authResource + * + * @description + * Logs the Umbraco backoffice user in if the credentials are good + * + * ##usage + * 
+         * authResource.performLogin(login, password)
+         *    .then(function(data) {
+         *        //Do stuff for login...
+         *    });
+         *
+ * @param {string} login Username of backoffice user + * @param {string} password Password of backoffice user + * @returns {Promise} resourcePromise object + * + */ performLogin: function (username, password) { if (!username || !password) { @@ -28,6 +52,24 @@ function authResource($q, $http, umbRequestHelper, angularHelper) { 'Login failed for user ' + username); }, + /** + * @ngdoc method + * @name umbraco.resources.authResource#performLogout + * @methodOf umbraco.resources.authResource + * + * @description + * Logs out the Umbraco backoffice user + * + * ##usage + * 
+         * authResource.performLogout()
+         *    .then(function(data) {
+         *        //Do stuff for logging out...
+         *    });
+         *
+ * @returns {Promise} resourcePromise object + * + */ performLogout: function() { return umbRequestHelper.resourcePromise( $http.post( @@ -36,7 +78,24 @@ function authResource($q, $http, umbRequestHelper, angularHelper) { "PostLogout"))); }, - /** Sends a request to the server to get the current user details, will return a 401 if the user is not logged in */ + /** + * @ngdoc method + * @name umbraco.resources.authResource#getCurrentUser + * @methodOf umbraco.resources.authResource + * + * @description + * Sends a request to the server to get the current user details, will return a 401 if the user is not logged in + * + * ##usage + * 
+         * authResource.getCurrentUser()
+         *    .then(function(data) {
+         *        //Do stuff for fetching the current logged in Umbraco backoffice user
+         *    });
+         *
+ * @returns {Promise} resourcePromise object + * + */ getCurrentUser: function () { return umbRequestHelper.resourcePromise( @@ -47,7 +106,24 @@ function authResource($q, $http, umbRequestHelper, angularHelper) { 'Server call failed for getting current user'); }, - /** Checks if the user is logged in or not - does not return 401 or 403 */ + /** + * @ngdoc method + * @name umbraco.resources.authResource#isAuthenticated + * @methodOf umbraco.resources.authResource + * + * @description + * Checks if the user is logged in or not - does not return 401 or 403 + * + * ##usage + * 
+         * authResource.isAuthenticated()
+         *    .then(function(data) {
+         *        //Do stuff to check if user is authenticated
+         *    });
+         *
+ * @returns {Promise} resourcePromise object + * + */ isAuthenticated: function () { return umbRequestHelper.resourcePromise( @@ -72,8 +148,25 @@ function authResource($q, $http, umbRequestHelper, angularHelper) { } }); }, - - /** Gets the user's remaining seconds before their login times out */ + + /** + * @ngdoc method + * @name umbraco.resources.authResource#getRemainingTimeoutSeconds + * @methodOf umbraco.resources.authResource + * + * @description + * Gets the user's remaining seconds before their login times out + * + * ##usage + * 
+         * authResource.getRemainingTimeoutSeconds()
+         *    .then(function(data) {
+         *        //Number of seconds is returned
+         *    });
+         *
+ * @returns {Promise} resourcePromise object + * + */ getRemainingTimeoutSeconds: function () { return umbRequestHelper.resourcePromise(