0.2.0 Extend apiParam, apiSuccess, apiError with a grouping ability.

Add new Functions: apiParamTitle, apiSuccessTitle, apiErrorTitle

CHANGELOG.md

@@ -1,5 +1,14 @@
 # apiDoc Changelog
 
+#### 0.2.0
+Extend `@apiParam`, `@apiSuccess`, `@apiError` with a grouping ability. Example `@apiParam (group) varname`.
+view [@apiParam](http://apidocjs.com/#param-api-param)
+Add new Functions:
+* [@apiParamTitle](http://apidocjs.com/#param-api-param-title)
+* [@apiSuccessTitle](http://apidocjs.com/#param-api-success-title)
+* [@apiErrorTitle](http://apidocjs.com/#param-api-error-title)
+Minor Template-Bugfixes.
+
 #### 0.1.11
 Allow whitespace in apiName and apiGroup.
 Bugfix filter for directories.
@@ -18,7 +27,7 @@ Fix for whitespace before comment block (Brandon Hamilton https://github.com/api
 Change templates, enable navigation scroll.
 
 #### 0.1.7
-Add [@apiIgnore`](http://apidocjs.com/#param-api-ignore).
+Add [@apiIgnore](http://apidocjs.com/#param-api-ignore).
 Update grunt Modules.
 
 #### 0.1.6

lib/apidoc.js

@@ -90,24 +90,32 @@ var app = {
 		apierror                 : "./plugins/parser_api_error.js",
 		apierrorexample          : "./plugins/parser_api_error_example.js",
 		apierrorstructure        : "./plugins/parser_api_error_structure.js",
+		apierrortitle            : "./plugins/parser_api_error_title.js",
 		apiexample               : "./plugins/parser_api_example.js",
 		apigroup                 : "./plugins/parser_api_group.js",
 		apiinfo                  : "./plugins/parser_api_info.js",
 		apiinfoexample           : "./plugins/parser_api_info_example.js",
+		apiinfotitle             : "./plugins/parser_api_info_title.js",
 		apiname                  : "./plugins/parser_api_name.js",
 		apiparam                 : "./plugins/parser_api_param.js",
+		apiparamtitle            : "./plugins/parser_api_param_title.js",
 		apipermission            : "./plugins/parser_api_permission.js",
 		apistructure             : "./plugins/parser_api_structure.js",
 		apisuccess               : "./plugins/parser_api_success.js",
 		apisuccessexample        : "./plugins/parser_api_success_example.js",
 		apisuccessstructure      : "./plugins/parser_api_success_structure.js",
+		apisuccesstitle          : "./plugins/parser_api_success_title.js",
 		apiversion               : "./plugins/parser_api_version.js"
 	},
 	workers: {
 		workererrorstructure     : "./plugins/worker_error_structure.js",
+		workererrortitle         : "./plugins/worker_error_title.js",
+		workerinfotitle          : "./plugins/worker_info_title.js",
 		workerpermission         : "./plugins/worker_permission.js",
 		workerstructure          : "./plugins/worker_structure.js",
-		workersuccessstructure   : "./plugins/worker_success_structure.js"
+		workerparamtitle         : "./plugins/worker_param_title.js",
+		workersuccessstructure   : "./plugins/worker_success_structure.js",
+		workersuccesstitle       : "./plugins/worker_success_title.js"
 	}
 }; // app
 
@@ -183,7 +191,8 @@ function createOutputFiles(parsedFiles, parsedFilenames, packageInfos)
 		for(var blockIndex = 0; blockIndex < parsedFile.length; blockIndex += 1)
 		{
 			var block = parsedFile[blockIndex];
-			if(Object.keys(block.global).length === 0 && Object.keys(block.local).length > 0)
+			// "<= 1" if successTitle gets removed, empty Object remain.
+			if(Object.keys(block.global).length <= 1 && Object.keys(block.local).length > 0)
 			{
 				// Add needed Elements for sorting
 				if( ! block.local.group) block.local.group = path.basename( parsedFilenames[fileIndex] );

lib/parser.js

@@ -135,7 +135,7 @@ Parser.prototype._parseBlockElements = function(indexApiBlocks, detectedElements
 					if(Object.keys(blockData.global).length > 0)
 					{
 						throw new Error("Can't set \"@" + element.sourceName + "\" in file \"" + self.filename +
-							"\" block number " + (blockIndex + 1) + ", only one define or use is allowed in the same block."
+							"\" block number " + (blockIndex + 1) + ", only one definition or use is allowed in the same block."
 						);
 					}
 				}
@@ -147,18 +147,23 @@ Parser.prototype._parseBlockElements = function(indexApiBlocks, detectedElements
 					// Only one global allowed per block
 					if(pushTo === "global" || pushTo.substr(0, 7) === "global.")
 					{
-						if(Object.keys(blockData.global).length > 0)
-						{
-							throw new Error("Can't set \"@" + element.sourceName + "\" in file \"" + self.filename +
-								"\" block number " + (blockIndex + 1) + ", only one define per block allowed."
-							);
-						}
+						var allowMultiple = self.parsers[element.name].allowMultiple || false;
 
-						if(preventGlobal === true)
+						if( ! allowMultiple)
 						{
-							throw new Error("Can't set \"@" + element.sourceName + "\" in file \"" + self.filename +
-								"\" block number " + (blockIndex + 1) + ", only one define or use is allowed in the same block."
-							);
+							if(Object.keys(blockData.global).length > 0)
+							{
+								throw new Error("Can't set \"@" + element.sourceName + "\" in file \"" + self.filename +
+									"\" block number " + (blockIndex + 1) + ", only one definition per block allowed."
+								);
+							}
+
+							if(preventGlobal === true)
+							{
+								throw new Error("Can't set \"@" + element.sourceName + "\" in file \"" + self.filename +
+									"\" block number " + (blockIndex + 1) + ", only one definition or use is allowed in the same block."
+								);
+							}
 						}
 					}
 

lib/plugins/filter_api_error.js

@@ -10,7 +10,7 @@ var filterApiParam = require("./filter_api_param.js");
  */
 function postFilter(parsedFiles, filenames)
 {
-	filterApiParam._postFilter(parsedFiles, filenames, "error");
+	filterApiParam.postFilter(parsedFiles, filenames, "error");
 } // postFilter
 
 /**

lib/plugins/filter_api_info.js

@@ -10,7 +10,7 @@ var filterApiParam = require("./filter_api_param.js");
  */
 function postFilter(parsedFiles, filenames)
 {
-	filterApiParam._postFilter(parsedFiles, filenames, "info");
+	filterApiParam.postFilter(parsedFiles, filenames, "info");
 } // postFilter
 
 /**

lib/plugins/filter_api_param.js

@@ -1,15 +1,3 @@
-/**
- * Post Filter parsed results.
- *
- * @param {Object[]} parsedFiles
- * @param {String[]} filenames
- * @returns {Object}
- */
-function postFilter(parsedFiles, filenames)
-{
-	_postFilter(parsedFiles, filenames, "parameter");
-} // postFilter
-
 /**
  * Post Filter parsed results.
  *
@@ -19,8 +7,9 @@ function postFilter(parsedFiles, filenames)
  * @returns {Object}
  * @todo Use elegant Map and Reduce Funktions.
  */
-function _postFilter(parsedFiles, filenames, tagName)
+function postFilter(parsedFiles, filenames, tagName)
 {
+	tagName = tagName || "parameter";
 	for(var fileIndex = 0; fileIndex < parsedFiles.length; fileIndex += 1)
 	{
 		var parsedFile = parsedFiles[fileIndex];
@@ -29,29 +18,34 @@ function _postFilter(parsedFiles, filenames, tagName)
 			var block = parsedFile[blockIndex];
 			if(block["local"][tagName] && block["local"][tagName]["fields"])
 			{
-				// Remove double field params, 1st is newest and is ok
-				var fields = block["local"][tagName]["fields"];
-				var newFields = [];
-				var keys = {};
-				for(var fieldIndex = 0; fieldIndex < fields.length; fieldIndex += 1)
+				var blockFields = block["local"][tagName]["fields"];
+				var blockFieldKeys = Object.keys(blockFields);
+				for(var blockFieldKeysIndex = 0; blockFieldKeysIndex < blockFieldKeys.length; blockFieldKeysIndex += 1)
 				{
-					var key = fields[fieldIndex].field;
-					if( ! keys[key])
+					var blockFieldKey = blockFieldKeys[blockFieldKeysIndex];
+					// Remove double field params, 1st is newest and is ok
+					var fields = block["local"][tagName]["fields"][blockFieldKey];
+					var newFields = [];
+					var keys = {};
+					for(var fieldIndex = 0; fieldIndex < fields.length; fieldIndex += 1)
 					{
-						keys[key] = 1;
-						newFields.push(fields[fieldIndex]);
-					}
-				} // for fieldIndex
-				block["local"][tagName]["fields"] = newFields;
+						var key = fields[fieldIndex].field;
+						if( ! keys[key])
+						{
+							keys[key] = 1;
+							newFields.push(fields[fieldIndex]);
+						}
+					} // for fieldIndex
+					block["local"][tagName]["fields"][blockFieldKey] = newFields;
+				} // for blockFieldKeysIndex
 			}
 		} // for blockIndex
 	} // for fileIndex
-} // _postFilter
+} // postFilter
 
 /**
  * Exports.
  */
 module.exports = {
-	postFilter: postFilter,
-	_postFilter: _postFilter
+	postFilter: postFilter
 };

lib/plugins/filter_api_success.js

@@ -10,7 +10,7 @@ var filterApiParam = require("./filter_api_param.js");
  */
 function postFilter(parsedFiles, filenames)
 {
-	filterApiParam._postFilter(parsedFiles, filenames, "success");
+	filterApiParam.postFilter(parsedFiles, filenames, "success");
 } // postFilter
 
 /**

lib/plugins/parser_api_error.js

@@ -1,15 +1,20 @@
 // Same as @apiparam
 var apiParam = require("./parser_api_param.js");
 
+function parse(content, source)
+{
+	return apiParam.parse(content, source, "Error 4xx");
+}
+
 function pushTo()
 {
-	return "local.error.fields";
+	return "local.error.fields." + apiParam.getGroup();
 }
 
 /**
  * Exports.
  */
 module.exports = {
-	parse: apiParam.parse,
+	parse: parse,
 	pushTo: pushTo
 };

lib/plugins/parser_api_error_title.js

@@ -0,0 +1,21 @@
+var apiParser = require("./parser_api_param_title.js");
+
+function parse(content, source)
+{
+	return apiParser.parse(content, source);
+} // parse
+
+function pushTo()
+{
+	return "global.errorTitle";
+}
+
+/**
+ * Exports.
+ */
+module.exports = {
+	parse: parse,
+	pushTo: pushTo,
+	getGroup: apiParser.getGroup,
+	allowMultiple: true
+};

lib/plugins/parser_api_info.js

@@ -1,15 +1,20 @@
 // Same as @apiparam
 var apiParam = require("./parser_api_param.js");
 
+function parse(content, source)
+{
+	return apiParam.parse(content, source, "Info");
+}
+
 function pushTo()
 {
-	return "local.info.fields";
+	return "local.info.fields." + apiParam.getGroup();
 }
 
 /**
  * Exports.
  */
 module.exports = {
-	parse: apiParam.parse,
+	parse: parse,
 	pushTo: pushTo
 };

lib/plugins/parser_api_info_title.js

@@ -0,0 +1,21 @@
+var apiParser = require("./parser_api_param_title.js");
+
+function parse(content, source)
+{
+	return apiParser.parse(content, source);
+} // parse
+
+function pushTo()
+{
+	return "global.infoTitle";
+}
+
+/**
+ * Exports.
+ */
+module.exports = {
+	parse: parse,
+	pushTo: pushTo,
+	getGroup: apiParser.getGroup,
+	allowMultiple: true
+};

lib/plugins/parser_api_param.js

@@ -1,16 +1,23 @@
-function parse(content)
+var group = "";
+
+function parse(content, source, defaultGroup)
 {
 	// Trim
 	content = content.replace(/^\s+|\s+$/g, "");
 
 	// Replace Linebreak with Unicode
 	content = content.replace(/\n/g, "\uffff");
 
-	// Search: type, field, defaultValue, optional, description
+	// Search: group, type, field, defaultValue, optional, description
 	// Example: {Boolean} [user.name="Default Value"] Users lastname.
 	// RegExp:
 	//     ^
 	//     (?:
+	//       (?:\(
+	//         (.+?)                 ; group
+	//       \))
+	//     \s*)?
+	//     (?:
 	//       (?:\{
 	//         (.+?)                 ; type
 	//       \})
@@ -24,8 +31,7 @@ function parse(content)
 	//      \s*
 	//     (.*)?                     ; description
 	//     (^@|$)                    ; Multiline
-	//var parseRegExp = /^(?:(?:\{(.+?)\})\s*)?(\[?(\S[a-zA-Z0-9._\-]*)(?:=['|"]?([\s.a-zA-Z0-9_\-]*)['|"]?)?\]?)\s*(.*)?$/g;
-	var parseRegExp = /^(?:(?:\{(.+?)\})\s*)?(\[?(\S[a-zA-Z0-9._\-]*)(?:=['|"]?([\s.a-zA-Z0-9_\-]*)['|"]?)?\]?)\s*(.*)?(^@|$)/g;
+	var parseRegExp = /^(?:(?:\((.+?)\))\s*)?(?:(?:\{(.+?)\})\s*)?(\[?(\S[a-zA-Z0-9._\-]*)(?:=['|"]?([\s.a-zA-Z0-9_\-]*)['|"]?)?\]?)\s*(.*)?(^@|$)/g;
 	var matches = parseRegExp.exec(content);
 //	function objectValuesToString(obj)
 //	{
@@ -67,26 +73,35 @@ function parse(content)
 	if( ! matches) return null;
 
 	// Reverse Unicode Linebreaks
-	if(matches[5]) matches[5] = matches[5].replace(/\uffff/g, "\n");
+	if(matches[6]) matches[6] = matches[6].replace(/\uffff/g, "\n");
+
+	group = matches[1] || defaultGroup || "Parameter";
 
 	return {
-		type: matches[1],
-		field: matches[3],
-		defaultValue: matches[4],
-		optional: (matches[2] !== matches[3]) ? true : false,
-		description: matches[5]
+		group: group,
+		type: matches[2],
+		field: matches[4],
+		defaultValue: matches[5],
+		optional: (matches[3] !== matches[4]) ? true : false,
+		description: matches[6] || ""
 	};
 } // parse
 
 function pushTo()
 {
-	return "local.parameter.fields";
+	return "local.parameter.fields." + getGroup();
+}
+
+function getGroup()
+{
+	return group;
 }
 
 /**
  * Exports.
  */
 module.exports = {
 	parse: parse,
-	pushTo: pushTo
+	pushTo: pushTo,
+	getGroup: getGroup
 };