From 789fdbbf1c5aa83a69941e7591a18ce812e8518b Mon Sep 17 00:00:00 2001
From: Gustavo Martin Morcuende <gu.martinm@gmail.com>
Date: Fri, 21 Aug 2015 16:46:22 +0200
Subject: [PATCH] showcase: update documentation with @ngdoc

---
 angularjs/showcase/.jscsrc     |  7 +++-
 angularjs/showcase/gulpfile.js | 79 ++++++++++++++++++++++++++++++++++++------
 2 files changed, 74 insertions(+), 12 deletions(-)

diff --git a/angularjs/showcase/.jscsrc b/angularjs/showcase/.jscsrc
index cb1cd00..194fb59 100644
--- a/angularjs/showcase/.jscsrc
+++ b/angularjs/showcase/.jscsrc
@@ -54,7 +54,12 @@
   "disallowSpacesInsideParentheses": true,
 
   "jsDoc": {
-    "checkAnnotations": true,
+    "checkAnnotations": {
+      "preset": "jsdoc3",
+      "extra": {
+        "ngdoc": true
+      }
+    },
     "checkParamNames": true,
     "requireParamTypes": true,
     "checkReturnTypes": true,
diff --git a/angularjs/showcase/gulpfile.js b/angularjs/showcase/gulpfile.js
index eb1d878..b0ec792 100644
--- a/angularjs/showcase/gulpfile.js
+++ b/angularjs/showcase/gulpfile.js
@@ -22,9 +22,12 @@ gulp.task('help', plugins.taskListing);
 gulp.task('default', ['help']);
 
 /**
+ * @ngdoc function
+ *
+ * @description
  * vet (evaluate) the code and create coverage report.
  *
- * @return {stream}
+ * @returns {stream}
  */
 gulp.task('vet', function() {
 
@@ -42,9 +45,12 @@ gulp.task('vet', function() {
 });
 
 /**
+ * @ngdoc function
+ *
+ * @description
  * wire up bower dependencies and inject files in index.html
  *
- * @return {Stream}
+ * @returns {Stream}
  */
 gulp.task('wiredep', function() {
 
@@ -60,9 +66,12 @@ gulp.task('wiredep', function() {
 });
 
 /**
+ * @ngdoc function
+ *
+ * @description
  * wire up bower dependencies and inject files in karma.conf.js
  *
- * @return {Stream}
+ * @returns {Stream}
  */
 gulp.task('wiredepkarma', function() {
 
@@ -76,6 +85,9 @@ gulp.task('wiredepkarma', function() {
 });
 
 /**
+ * @ngdoc function
+ *
+ * @description
  * Runs HTTP server.
  */
 gulp.task('server', ['wiredep'], function(done) {
@@ -92,9 +104,12 @@ gulp.task('server', ['wiredep'], function(done) {
 });
 
 /**
+ * @ngdoc function
+ *
+ * @description
  * Runs specs once and exit.
  *
- * @return {Stream}
+ * @returns {Stream}
  */
 gulp.task('test', ['vet', 'wiredepkarma'], function(done) {
 
@@ -104,6 +119,9 @@ gulp.task('test', ['vet', 'wiredepkarma'], function(done) {
 });
 
 /**
+ * @ngdoc function
+ *
+ * @description
  * Run specs and wait. Watch for file changes and re-run tests on each change
  */
 gulp.task('autotest', ['wiredepkarma'], function(done) {
@@ -114,9 +132,12 @@ gulp.task('autotest', ['wiredepkarma'], function(done) {
 });
 
 /**
+ * @ngdoc function
+ *
+ * @description
  * Builds application for production.
  *
- * @return {stream} The stream.
+ * @returns {stream} The stream.
  */
 gulp.task('build', ['wiredep', 'test', 'templatecache'], function() {
 
@@ -197,9 +218,12 @@ gulp.task('build', ['wiredep', 'test', 'templatecache'], function() {
     .pipe(gulp.dest(config.build.directory));
 
   /**
+   * @ngdoc function
+   *
+   * @description
    * Format and return the header for files
    *
-   * @return {stream} The stream.
+   * @returns {stream} The stream.
    */
   function getHeader() {
     var pkg = require('./package.json');
@@ -220,9 +244,12 @@ gulp.task('build', ['wiredep', 'test', 'templatecache'], function() {
 });
 
 /**
+ * @ngdoc function
+ *
+ * @description
  * Cleans up files in distribution directory.
  *
- * @return {undefined}
+ * @returns {undefined}
  */
 gulp.task('clean', function(done) {
 
@@ -233,9 +260,12 @@ gulp.task('clean', function(done) {
 });
 
 /**
+ * @ngdoc function
+ *
+ * @description
  * Creates $templateCache from html templates
  *
- * @return {stream}
+ * @returns {stream}
  */
 gulp.task('templatecache', ['clean'], function() {
 
@@ -260,11 +290,14 @@ gulp.task('templatecache', ['clean'], function() {
 });
 
 /**
+ * @ngdoc function
+ *
+ * @description
  * Inject files in a sorted sequence at a specified inject label.
  *
  * @param {Array|string} source Source files (glob patterns)
  * @param {string=} label The label name to be used by gulp-inject.
- * @return {stream} The stream.
+ * @returns {stream} The stream.
  */
 function inject(source, label) {
   var options = {relative: false};
@@ -278,10 +311,13 @@ function inject(source, label) {
 }
 
 /**
+ * @ngdoc function
+ *
+ * @description
  * Runs HTTP server.
  *
  * @param  {string=} [environment='development'] development or production environments.
- * @return {undefined}
+ * @returns {undefined}
  */
 function server(environment) {
   var nodeOptions = {
@@ -310,11 +346,14 @@ function server(environment) {
 }
 
 /**
+ * @ngdoc function
+ *
+ * @description
  * Tests runner, karma launcher.
  *
  * @param  {boolean} singleRun True means run once and end (continuous integration), or keep running (development)
  * @param  {function} done Callback to fire when karma is done
- * @return {undefined}
+ * @returns {undefined}
  */
 function startTests(singleRun, done) {
   var excludeFiles = [];
@@ -334,10 +373,28 @@ function startTests(singleRun, done) {
   }
 }
 
+/**
+ * @ngdoc function
+ *
+ * @description
+ * Log messages to CLI.
+ *
+ * @param  {string} message The message to be shown.
+ * @returns {undefined}
+ */
 function log(message) {
   plugins.util.log(plugins.util.colors.blue(message));
 }
 
+/**
+ * @ngdoc function
+ *
+ * @description
+ * Format data generated by the gulp-bytediff plugin.
+ *
+ * @param  {Object} data The data created by gulp-bytediff plugin.
+ * @returns {string}
+ */
 function byteDiffFormat(data) {
   var difference = (data.savings > 0) ? ' smaller.' : ' larger.';
   return data.fileName + ' is ' + data.percent + '%' + difference;
-- 
2.1.4