Merge pull request pencilblue#694 from pencilblue/documentation_cleanup

Cleaned up documentation syntax errors

controllers/base_controller.js

@@ -398,7 +398,7 @@ module.exports = function BaseControllerModule(pb) {
      * (BaseController.getDefaultSanitizationRules) or those provided by the call
      * to BaseController.getSanitizationRules.
      * @method sanitizeObject
-     * @param {Object}
+     * @param {Object} obj
      */
     BaseController.prototype.sanitizeObject = function(obj) {
         if (!util.isObject(obj)) {
@@ -418,6 +418,7 @@ module.exports = function BaseControllerModule(pb) {
     /**
      *
      * @method getSanitizationRules
+     * @return {Object}
      */
     BaseController.prototype.getSanitizationRules = function() {
         return {};

include/access_management.js

@@ -172,7 +172,7 @@ module.exports = function(pb) {
      * @method authenticateSession
      * @param {Object} session
      * @param {Object} options
-     * @param {Authentication}
+     * @param {Authentication} authenticator
      * @param {Function} cb
      */
     SecurityService.authenticateSession = function(session, options, authenticator, cb){

include/admin_navigation.js

@@ -218,7 +218,7 @@ module.exports = function AdminNavigationModule(pb) {
      * @private
      * @static
      * @method getDefaultNavigation
-     * @returns {Array}
+     * @return {Array}
      */
     function getDefaultNavigation() {
         return util.clone(DEFAULT_NAV);
@@ -229,7 +229,7 @@ module.exports = function AdminNavigationModule(pb) {
      * @private
      * @static
      * @method getAdditions
-     * @returns {Array}
+     * @return {Array}
      */
     function getAdditions() {
         return util.clone(AdminNavigation.additions);
@@ -240,7 +240,7 @@ module.exports = function AdminNavigationModule(pb) {
      * @private
      * @static
      * @method getChildrenAdditions
-     * @returns {Object}
+     * @return {Object}
      */
     function getChildrenAdditions() {
         return util.clone(AdminNavigation.childrenAdditions);
@@ -251,7 +251,7 @@ module.exports = function AdminNavigationModule(pb) {
      * @private
      * @static
      * @method buildNavigation
-     * @returns {Array}
+     * @return {Array}
      */
     function buildNavigation() {
         var i;
@@ -300,7 +300,7 @@ module.exports = function AdminNavigationModule(pb) {
      * @method localizeNavigation
      * @param navigation
      * @param ls
-     * @returns {*}
+     * @return {*}
      */
     function localizeNavigation(navigation, ls) {
         navigation.forEach(function(nav) {
@@ -318,7 +318,7 @@ module.exports = function AdminNavigationModule(pb) {
      * @method isDuplicate
      * @param {String} id
      * @param {Array} navigation
-     * @returns {boolean}
+     * @return {boolean}
      */
     function isDuplicate(id, navigation) {
         if (!navigation) {
@@ -374,7 +374,7 @@ module.exports = function AdminNavigationModule(pb) {
      * @method addChild
      * @param {String} parentId
      * @param {Object} node
-     * @returns {Boolean}
+     * @return {Boolean}
      */
     AdminNavigation.addChild = function (parentId, node) {
         if (isDuplicate(node.id)) {
@@ -394,7 +394,7 @@ module.exports = function AdminNavigationModule(pb) {
      * @static
      * @method add
      * @param {Object} node
-     * @returns {Boolean}
+     * @return {Boolean}
      */
     AdminNavigation.add = function (node) {
         if (isDuplicate(node.id)) {
@@ -411,7 +411,7 @@ module.exports = function AdminNavigationModule(pb) {
      * @method remove
      * @param id
      * @param navigation
-     * @returns {boolean}
+     * @return {boolean}
      */
     AdminNavigation.remove = function (id) {
         if (!isDuplicate(id, buildNavigation())) {
@@ -453,7 +453,7 @@ module.exports = function AdminNavigationModule(pb) {
      * @param {Object} session
      * @param {Array} adminNavigation
      * @param {Array} activeItems
-     * @returns {Array}
+     * @return {Array}
      */
     AdminNavigation.removeUnauthorized = function (session, adminNavigation, activeItems) {
         for (var i = 0; i < adminNavigation.length; i++) {

include/config.js

@@ -32,6 +32,8 @@ var winston = require('winston');
  * 1) copy "sample.config.json" to "/etc/pencilblue/config.json"
  * 2) Override the properties as desired.
  * 3) Add any custom properties you wish to provide for your specific purposes.
+ * @class Configuration
+ * @constructor
  */
 function Configuration(){}
 
@@ -689,6 +691,9 @@ var BASE_CONFIG = {
 
 /** 
  * Retrieve the base configuration
+ * @static
+ * @method getBaseConfig
+ * @return {Object}
  */
 Configuration.getBaseConfig = function() {
     return util.clone(BASE_CONFIG);
@@ -699,6 +704,10 @@ Configuration.getBaseConfig = function() {
  * NOTE: This should only be called once by the core code at startup.  Calling
  * this function after the server starts may cause unintended behavior across
  * the system.
+ * @static
+ * @method load
+ * @param {Array|String} filePaths
+ * @return {Object}
  */
 Configuration.load = function(filePaths) {
     if (util.isString(filePaths)) {

include/http/request_handler.js

@@ -243,7 +243,7 @@ module.exports = function RequestHandlerModule(pb) {
      * through the setup process in order to pass validation
      * @param {Boolean} [descriptor.auth_required=false] If true, the user making the
      * request must have successfully authenticated against the system.
-     * @request {String} [descriptor.content_type='text/html'] The content type header sent with the response
+     * @param {String} [descriptor.content_type='text/html'] The content type header sent with the response
      * @param {String} theme The plugin/theme UID
      * @return {Boolean} TRUE if the route was registered, FALSE if not
      */
@@ -628,7 +628,7 @@ module.exports = function RequestHandlerModule(pb) {
     /**
      * Compares the path against the registered routes's to lookup the route object.
      * @method getRoute
-     * @path {String} path The URL path for the incoming request
+     * @param {String} path The URL path for the incoming request
      * @return {Object} The route object or NULL if the path does not match any route
      */
     RequestHandler.prototype.getRoute = function(path) {

include/localization.js

@@ -93,7 +93,7 @@ module.exports = function LocalizationModule(pb) {
      * @method localize
      * @param {array} sets The localizations sets to search in
      * @param {string} text The text to localize
-     * @returns {string} The text where keys have been replaced with translated values
+     * @return {string} The text where keys have been replaced with translated values
      */
     Localization.prototype.localize = function(sets, text){
         if (pb.log.isSilly()) {
@@ -136,7 +136,7 @@ module.exports = function LocalizationModule(pb) {
      * @param {String} key
      * @param {String|Integer|Float|Object} [args] The variable number of 
      * parameters to be injected into the localization value
-     * @returns {string} The formatted and localized string
+     * @return {string} The formatted and localized string
      */
     Localization.prototype.get = function() {
         var key = arguments[0];
@@ -187,7 +187,7 @@ module.exports = function LocalizationModule(pb) {
      *
      * @method best
      * @param {Object} request The request object
-     * @returns {string} Locale for the request
+     * @return {string} Locale for the request
      */
     Localization.best = function(request){
         var loc = 'en-us';

include/requirements.js

@@ -21,7 +21,9 @@ var path = require('path');
 /**
  * Requirements - Responsible for declaring all of the system types and modules
  * needed to construct the system API object.
- * @copyright PencilBlue, all rights reserved.
+ * @class PB
+ * @param {Object} config
+ * @return {Object} The pb namespace
  */
 module.exports = function PB(config) {
 

include/service/entities/article_service.js

@@ -214,19 +214,19 @@ module.exports = function ArticleServiceModule(pb) {
 
     /**
      * Updates articles
-     *
+     * @method update
      * @param {String} articleId	id of article
      * @param {Object} fields	fields to update
      * @param {Object} options
      * @param {Function} cb      Callback function
      */
     ArticleService.prototype.update = function(articleId, fields, options, cb) {
-            if(!util.isObject(fields)){
-                    return cb(new Error('The fields parameter is required'));
-            }
+        if(!util.isObject(fields)){
+                return cb(new Error('The fields parameter is required'));
+        }
 
         var where = pb.DAO.getIdWhere(articleId);
-            var content_type = this.getContentType();
+        var content_type = this.getContentType();
 
         var dao  = new pb.DAO();
         dao.updateFields(content_type, where, fields, options, cb);
@@ -524,6 +524,7 @@ module.exports = function ArticleServiceModule(pb) {
      * Provided the content descriptor and the content settings object the 
      * function indicates if comments should be allowed within the given 
      * context of the content.
+     * @method allowComments
      * @param {Object} contentSettings The settings object retrieved from the 
      * content service
      * @param {Object} content The page or article that should or should not 
@@ -674,6 +675,7 @@ module.exports = function ArticleServiceModule(pb) {
 
     /**
      * Replaces an article or page layout's ^media_display^ tag with a media embed
+     * @method replaceMediaTag
      * @param {String}   layout        The HTML layout of the article or page
      * @param {String}   mediaTemplate The template of the media embed
      * @param {Function} cb            Callback function

include/service/entities/content/article_renderer.js

@@ -357,10 +357,11 @@ module.exports = function(pb) {
     };
 
     /**
+     *
      * @method getReadMoreSpan
      * @param {Object} content
      * @param {String} anchorContent
-     * @reurn {String}
+     * @return {String}
      */
     ArticleRenderer.prototype.getReadMoreSpan = function(content, anchorContent) {
         return '&nbsp<span class="read_more">' + this.getReadMoreLink(content, anchorContent) + '</span>';

include/service/entities/custom_object_service.js

@@ -703,6 +703,7 @@ module.exports = function CustomObjectServiceModule(pb) {
 
     /**
      * Validates the fields of a custom object
+     * @method validateCustObjFields
      * @param {Object} custObj The object to validate
      * @param {Object} custObjType The custom object type to validate against
      * @param {Function} cb A callback that takes two parameters. The first is an
@@ -931,7 +932,8 @@ module.exports = function CustomObjectServiceModule(pb) {
     /**
      * Deletes a custom object by ID
      * @method deleteById
-     * @param {String} 
+     * @param {String} id
+     * @param {Function} cb
      */
     CustomObjectService.prototype.deleteById = function(id, cb) {
         var dao = new pb.DAO();
@@ -978,7 +980,7 @@ module.exports = function CustomObjectServiceModule(pb) {
      * @param {String|Object} custObjType A string ID of the custom object type or 
      * the custom object type itself.
      * @param {Object} [options={}]
-     * @param 
+     * @param {Function} cb
      */
     CustomObjectService.prototype.deleteForType = function(custObjType, cb) {
 

include/service/entities/plugin_service.js

@@ -1891,7 +1891,7 @@ module.exports = function PluginServiceModule(pb) {
      * Validates the path of a main module file.  The path is considered valid if
      * the path points to JS file.  The path may be absolute or relative to the
      * specific plugin directory.
-     *
+     * @method validateMainModulePath
      * @param mmPath The relative or absolute path to the main module file
      * @param pluginDirName The name of the directory housing the plugin
      * @return {Boolean} TRUE if the path is valid, FALSE if not
@@ -1902,7 +1902,7 @@ module.exports = function PluginServiceModule(pb) {
 
     /**
      * Validates a setting from a details.json file.
-     *
+     * @method validateSetting
      * @param setting The setting to validate
      * @param position The position in the settings array where the setting resides
      * as a 0 based index.

include/service/entities/section_service.js

@@ -286,7 +286,7 @@ module.exports = function SectionServiceModule(pb) {
      *
      * @method getParentSelectList
      * @param {String|ObjectID} currItem
-     * @param {Function}
+     * @param {Function} cb
      */
     SectionService.prototype.getParentSelectList = function(currItem, cb) {
         cb = cb || currItem;
@@ -314,7 +314,7 @@ module.exports = function SectionServiceModule(pb) {
      *
      * @static
      * @method trimForType
-     * @param {Object}
+     * @param {Object} navItem
      */
     SectionService.trimForType = function(navItem) {
         if (navItem.type === 'container') {
@@ -346,7 +346,7 @@ module.exports = function SectionServiceModule(pb) {
     /**
      *
      * @method validate
-     * @param {Object}
+     * @param {Object} navItem
      * @param {Function} cb
      */
     SectionService.prototype.validate = function(navItem, cb) {
@@ -412,7 +412,7 @@ module.exports = function SectionServiceModule(pb) {
      *
      * @method validateLinkNavItem
      * @param {Object} navItem
-     * @param {Function}
+     * @param {Function} cb
      */
     SectionService.prototype.validateLinkNavItem = function(navItem, cb) {
         var errors = [];
@@ -690,7 +690,7 @@ module.exports = function SectionServiceModule(pb) {
      *
      * @static
      * @method formatUrl
-     * @param {Object}
+     * @param {Object} navItem
      */
     SectionService.formatUrl = function(navItem) {
         if (util.isString(navItem.link)) {

include/service/jobs/cluster_job_runner.js

@@ -148,6 +148,7 @@ module.exports = function ClusterJobRunnerModule(pb) {
     /**
      * Called when the tasks have completed execution and isInitiator = FALSE. The
      * function blindly passes the results of the tasks back to the callback.
+     * @method processWorkerResults
      * @param {Error} err The error that occurred (if any) during task execution
      * @param {Array} results An array containing the result of each executed task
      * @param {Function} cb A callback that provides two parameters: The first is

include/service/media/renderers/audio_media_renderer.js

@@ -88,7 +88,7 @@ module.exports = function AudioMediaRendererModule(pb) {
     /**
      * Retrieves the style for the specified type of view
      * @static
-     * @meethod getStyle
+     * @method getStyle
      * @param {String} viewType The view type calling for a styling
      * @return {Object} a hash of style properties
      */

include/service/media/renderers/daily_motion_media_renderer.js

@@ -71,7 +71,7 @@ module.exports = function AudioMediaRendererModule(pb) {
     /**
      * Retrieves the style for the specified type of view
      * @static
-     * @meethod getStyle
+     * @method getStyle
      * @param {String} viewType The view type calling for a styling
      * @return {Object} a hash of style properties
      */

include/service/media/renderers/image_media_renderer.js

@@ -90,7 +90,7 @@ module.exports = function ImageMediaRendererModule(pb) {
     /**
      * Retrieves the style for the specified type of view
      * @static
-     * @meethod getStyle
+     * @method getStyle
      * @param {String} viewType The view type calling for a styling
      * @return {Object} a hash of style properties
      */

include/service/media/renderers/instagram_media_renderer.js

@@ -67,7 +67,7 @@ module.exports = function InstagramMediaRendererModule(pb) {
     /**
      * Retrieves the style for the specified type of view
      * @static
-     * @meethod getStyle
+     * @method getStyle
      * @param {String} viewType The view type calling for a styling
      * @return {Object} a hash of style properties
      */

include/service/media/renderers/kickstarter_media_renderer.js

@@ -67,7 +67,7 @@ module.exports = function KickStarterMediaRendererModule(pb) {
     /**
      * Retrieves the style for the specified type of view
      * @static
-     * @meethod getStyle
+     * @method getStyle
      * @param {String} viewType The view type calling for a styling
      * @return {Object} a hash of style properties
      */