Update & grunt-groc and fix docs errors

issue #2622

- Updated grunt-groc to 0.4.5
- Fixed the few places which made the docs fail to generate
- There is still a mix of styles

core/client/assets/lib/jquery-utils.js

@@ -9,10 +9,10 @@
 
     /**
      * Allows to check contents of each element exactly
-     * @param obj
-     * @param index
-     * @param meta
-     * @param stack
+     * @param {Object} obj
+     * @param {*} index
+     * @param {*} meta
+     * @param {*} stack
      * @returns {boolean}
      */
     $.expr[":"].containsExact = function (obj, index, meta, stack) {
@@ -133,7 +133,7 @@
      * Set interactions for all menus and overlays
      * This finds all visible 'hideClass' elements and hides them upon clicking away from the element itself.
      * A callback can be defined to customise the results. By default it will hide the element.
-     * @param callback
+     * @param {Function} callback
      */
     $.fn.hideAway = function (callback) {
         var $self = $(this);

core/server/api/settings.js

@@ -98,16 +98,15 @@ readSettingsResult = function (result) {
     });
 };
 
-/**
- * Normalizes paths read by require-tree so that the apps and themes modules can use them.
- * Creates an empty array (res), and populates it with useful info about the read packages
- * like name, whether they're active (comparison with the second argument), and if they
- * have a package.json, that, otherwise false
- * @param  object           paths       as returned by require-tree()
- * @param  array/string     active      as read from the settings object
- * @return array                        of objects with useful info about
- *                                      apps / themes
- */
+
+// Normalizes paths read by require-tree so that the apps and themes modules can use them.
+// Creates an empty array (res), and populates it with useful info about the read packages
+// like name, whether they're active (comparison with the second argument), and if they
+// have a package.json, that, otherwise false
+// @param  {object}           paths       as returned by require-tree()
+// @param  {array/string}     active      as read from the settings object
+// @return {array}                        of objects with useful info about apps / themes
+
 filterPaths = function (paths, active) {
     var pathKeys = Object.keys(paths),
         res = [],

core/server/helpers/index.js

@@ -38,13 +38,13 @@ if (!isProduction) {
     hbs.handlebars.logger.level = 0;
 }
 
-/**
- * [ description]
- * @todo ghost core helpers + a way for themes to register them
- * @param  {Object} context date object
- * @param  {*} options
- * @return {Object} A Moment time / date object
- */
+
+ // [ description]
+ //
+ // @param  {Object} context date object
+ // @param  {*} options
+ // @return {Object} A Moment time / date object
+
 coreHelpers.date = function (context, options) {
     if (!options && context.hasOwnProperty('hash')) {
         options = context;
@@ -519,10 +519,10 @@ coreHelpers.meta_description = function (options) {
 /**
  * Localised string helpers
  *
- * @param String key
- * @param String default translation
+ * @param {String} key
+ * @param {String} default translation
  * @param {Object} options
- * @return String A correctly internationalised string
+ * @return {String} A correctly internationalised string
  */
 coreHelpers.e = function (key, defaultString, options) {
     var output;

core/server/models/base.js

@@ -112,7 +112,7 @@ ghostBookshelf.Model = ghostBookshelf.Model.extend({
 
     /**
      * Naive find all
-     * @param options (optional)
+     * @param {Object} options (optional)
      */
     findAll:  function (options) {
         options = options || {};
@@ -125,8 +125,8 @@ ghostBookshelf.Model = ghostBookshelf.Model.extend({
 
     /**
      * Naive find one where args match
-     * @param args
-     * @param options (optional)
+     * @param {Object} args
+     * @param {Object} options (optional)
      */
     findOne: function (args, options) {
         options = options || {};
@@ -139,8 +139,8 @@ ghostBookshelf.Model = ghostBookshelf.Model.extend({
 
     /**
      * Naive edit
-     * @param editedObj
-     * @param options (optional)
+     * @param {Object} editedObj
+     * @param {Object} options (optional)
      */
     edit: function (editedObj, options) {
         options = options || {};
@@ -157,8 +157,8 @@ ghostBookshelf.Model = ghostBookshelf.Model.extend({
 
     /**
      * Naive create
-     * @param newObj
-     * @param options (optional)
+     * @param {Object} newObj
+     * @param {Object} options (optional)
      */
     add: function (newObj, options) {
         options = options || {};
@@ -180,8 +180,8 @@ ghostBookshelf.Model = ghostBookshelf.Model.extend({
 
     /**
      * Naive destroy
-     * @param _identifier
-     * @param options (optional)
+     * @param {Object} _identifier
+     * @param {Object} options (optional)
      */
     destroy: function (_identifier, options) {
         options = options || {};

core/server/models/post.js

@@ -259,7 +259,7 @@ Post = ghostBookshelf.Model.extend({
      //     }
 
     /*
-     * @params opts
+     * @params {Object} opts
      */
     findPage: function (opts) {
         var postCollection = Posts.forge(),

core/server/models/user.js

@@ -77,7 +77,7 @@ User = ghostBookshelf.Model.extend({
 
     /**
      * Naive user add
-     * @param  _user
+     * @param {object} _user
      *
      * Hashes the password provided before saving to the database.
      */
@@ -218,7 +218,6 @@ User = ghostBookshelf.Model.extend({
     /**
      * Naive change password method
      * @param {object} _userdata email, old pw, new pw, new pw2
-     *
      */
     changePassword: function (_userdata) {
         var self = this,

package.json

@@ -72,7 +72,7 @@
         "grunt-contrib-uglify": "~0.2.5",
         "grunt-contrib-watch": "~0.5.3",
         "grunt-express-server": "~0.4.11",
-        "grunt-groc": "~0.4.0",
+        "grunt-groc": "~0.4.5",
         "grunt-mocha-cli": "~1.4.0",
         "grunt-shell": "~0.6.1",
         "grunt-update-submodules": "~0.2.1",