Skip to content

Commit 6180a42

Browse files
rottmannrottmann
committed
0.2.0 Extend apiParam, apiSuccess, apiError with a grouping ability.
Add new Functions: apiParamTitle, apiSuccessTitle, apiErrorTitle
1 parent a201744 commit 6180a42

39 files changed

+1564
-519
lines changed

‎CHANGELOG.md

+10-1
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,14 @@
11
# apiDoc Changelog
22

3+
#### 0.2.0
4+
Extend `@apiParam`, `@apiSuccess`, `@apiError` with a grouping ability. Example `@apiParam (group) varname`.
5+
view [@apiParam](http://apidocjs.com/#param-api-param)
6+
Add new Functions:
7+
* [@apiParamTitle](http://apidocjs.com/#param-api-param-title)
8+
* [@apiSuccessTitle](http://apidocjs.com/#param-api-success-title)
9+
* [@apiErrorTitle](http://apidocjs.com/#param-api-error-title)
10+
Minor Template-Bugfixes.
11+
312
#### 0.1.11
413
Allow whitespace in apiName and apiGroup.
514
Bugfix filter for directories.
@@ -18,7 +27,7 @@ Fix for whitespace before comment block (Brandon Hamilton https://github.com/api
1827
Change templates, enable navigation scroll.
1928

2029
#### 0.1.7
21-
Add [@apiIgnore`](http://apidocjs.com/#param-api-ignore).
30+
Add [@apiIgnore](http://apidocjs.com/#param-api-ignore).
2231
Update grunt Modules.
2332

2433
#### 0.1.6

‎lib/apidoc.js

+11-2
Original file line numberDiff line numberDiff line change
@@ -90,24 +90,32 @@ var app = {
9090
apierror : "./plugins/parser_api_error.js",
9191
apierrorexample : "./plugins/parser_api_error_example.js",
9292
apierrorstructure : "./plugins/parser_api_error_structure.js",
93+
apierrortitle : "./plugins/parser_api_error_title.js",
9394
apiexample : "./plugins/parser_api_example.js",
9495
apigroup : "./plugins/parser_api_group.js",
9596
apiinfo : "./plugins/parser_api_info.js",
9697
apiinfoexample : "./plugins/parser_api_info_example.js",
98+
apiinfotitle : "./plugins/parser_api_info_title.js",
9799
apiname : "./plugins/parser_api_name.js",
98100
apiparam : "./plugins/parser_api_param.js",
101+
apiparamtitle : "./plugins/parser_api_param_title.js",
99102
apipermission : "./plugins/parser_api_permission.js",
100103
apistructure : "./plugins/parser_api_structure.js",
101104
apisuccess : "./plugins/parser_api_success.js",
102105
apisuccessexample : "./plugins/parser_api_success_example.js",
103106
apisuccessstructure : "./plugins/parser_api_success_structure.js",
107+
apisuccesstitle : "./plugins/parser_api_success_title.js",
104108
apiversion : "./plugins/parser_api_version.js"
105109
},
106110
workers: {
107111
workererrorstructure : "./plugins/worker_error_structure.js",
112+
workererrortitle : "./plugins/worker_error_title.js",
113+
workerinfotitle : "./plugins/worker_info_title.js",
108114
workerpermission : "./plugins/worker_permission.js",
109115
workerstructure : "./plugins/worker_structure.js",
110-
workersuccessstructure : "./plugins/worker_success_structure.js"
116+
workerparamtitle : "./plugins/worker_param_title.js",
117+
workersuccessstructure : "./plugins/worker_success_structure.js",
118+
workersuccesstitle : "./plugins/worker_success_title.js"
111119
}
112120
}; // app
113121

@@ -183,7 +191,8 @@ function createOutputFiles(parsedFiles, parsedFilenames, packageInfos)
183191
for(var blockIndex = 0; blockIndex < parsedFile.length; blockIndex += 1)
184192
{
185193
var block = parsedFile[blockIndex];
186-
if(Object.keys(block.global).length === 0 && Object.keys(block.local).length > 0)
194+
// "<= 1" if successTitle gets removed, empty Object remain.
195+
if(Object.keys(block.global).length <= 1 && Object.keys(block.local).length > 0)
187196
{
188197
// Add needed Elements for sorting
189198
if( ! block.local.group) block.local.group = path.basename( parsedFilenames[fileIndex] );

‎lib/parser.js

+16-11
Original file line numberDiff line numberDiff line change
@@ -135,7 +135,7 @@ Parser.prototype._parseBlockElements = function(indexApiBlocks, detectedElements
135135
if(Object.keys(blockData.global).length > 0)
136136
{
137137
throw new Error("Can't set \"@" + element.sourceName + "\" in file \"" + self.filename +
138-
"\" block number " + (blockIndex + 1) + ", only one define or use is allowed in the same block."
138+
"\" block number " + (blockIndex + 1) + ", only one definition or use is allowed in the same block."
139139
);
140140
}
141141
}
@@ -147,18 +147,23 @@ Parser.prototype._parseBlockElements = function(indexApiBlocks, detectedElements
147147
// Only one global allowed per block
148148
if(pushTo === "global" || pushTo.substr(0, 7) === "global.")
149149
{
150-
if(Object.keys(blockData.global).length > 0)
151-
{
152-
throw new Error("Can't set \"@" + element.sourceName + "\" in file \"" + self.filename +
153-
"\" block number " + (blockIndex + 1) + ", only one define per block allowed."
154-
);
155-
}
150+
var allowMultiple = self.parsers[element.name].allowMultiple || false;
156151

157-
if(preventGlobal === true)
152+
if( ! allowMultiple)
158153
{
159-
throw new Error("Can't set \"@" + element.sourceName + "\" in file \"" + self.filename +
160-
"\" block number " + (blockIndex + 1) + ", only one define or use is allowed in the same block."
161-
);
154+
if(Object.keys(blockData.global).length > 0)
155+
{
156+
throw new Error("Can't set \"@" + element.sourceName + "\" in file \"" + self.filename +
157+
"\" block number " + (blockIndex + 1) + ", only one definition per block allowed."
158+
);
159+
}
160+
161+
if(preventGlobal === true)
162+
{
163+
throw new Error("Can't set \"@" + element.sourceName + "\" in file \"" + self.filename +
164+
"\" block number " + (blockIndex + 1) + ", only one definition or use is allowed in the same block."
165+
);
166+
}
162167
}
163168
}
164169

‎lib/plugins/filter_api_error.js

+1-1
Original file line numberDiff line numberDiff line change
@@ -10,7 +10,7 @@ var filterApiParam = require("./filter_api_param.js");
1010
*/
1111
function postFilter(parsedFiles, filenames)
1212
{
13-
filterApiParam._postFilter(parsedFiles, filenames, "error");
13+
filterApiParam.postFilter(parsedFiles, filenames, "error");
1414
} // postFilter
1515

1616
/**

‎lib/plugins/filter_api_info.js

+1-1
Original file line numberDiff line numberDiff line change
@@ -10,7 +10,7 @@ var filterApiParam = require("./filter_api_param.js");
1010
*/
1111
function postFilter(parsedFiles, filenames)
1212
{
13-
filterApiParam._postFilter(parsedFiles, filenames, "info");
13+
filterApiParam.postFilter(parsedFiles, filenames, "info");
1414
} // postFilter
1515

1616
/**

‎lib/plugins/filter_api_param.js

+22-28
Original file line numberDiff line numberDiff line change
@@ -1,15 +1,3 @@
1-
/**
2-
* Post Filter parsed results.
3-
*
4-
* @param {Object[]} parsedFiles
5-
* @param {String[]} filenames
6-
* @returns {Object}
7-
*/
8-
function postFilter(parsedFiles, filenames)
9-
{
10-
_postFilter(parsedFiles, filenames, "parameter");
11-
} // postFilter
12-
131
/**
142
* Post Filter parsed results.
153
*
@@ -19,8 +7,9 @@ function postFilter(parsedFiles, filenames)
197
* @returns {Object}
208
* @todo Use elegant Map and Reduce Funktions.
219
*/
22-
function _postFilter(parsedFiles, filenames, tagName)
10+
function postFilter(parsedFiles, filenames, tagName)
2311
{
12+
tagName = tagName || "parameter";
2413
for(var fileIndex = 0; fileIndex < parsedFiles.length; fileIndex += 1)
2514
{
2615
var parsedFile = parsedFiles[fileIndex];
@@ -29,29 +18,34 @@ function _postFilter(parsedFiles, filenames, tagName)
2918
var block = parsedFile[blockIndex];
3019
if(block["local"][tagName] && block["local"][tagName]["fields"])
3120
{
32-
// Remove double field params, 1st is newest and is ok
33-
var fields = block["local"][tagName]["fields"];
34-
var newFields = [];
35-
var keys = {};
36-
for(var fieldIndex = 0; fieldIndex < fields.length; fieldIndex += 1)
21+
var blockFields = block["local"][tagName]["fields"];
22+
var blockFieldKeys = Object.keys(blockFields);
23+
for(var blockFieldKeysIndex = 0; blockFieldKeysIndex < blockFieldKeys.length; blockFieldKeysIndex += 1)
3724
{
38-
var key = fields[fieldIndex].field;
39-
if( ! keys[key])
25+
var blockFieldKey = blockFieldKeys[blockFieldKeysIndex];
26+
// Remove double field params, 1st is newest and is ok
27+
var fields = block["local"][tagName]["fields"][blockFieldKey];
28+
var newFields = [];
29+
var keys = {};
30+
for(var fieldIndex = 0; fieldIndex < fields.length; fieldIndex += 1)
4031
{
41-
keys[key] = 1;
42-
newFields.push(fields[fieldIndex]);
43-
}
44-
} // for fieldIndex
45-
block["local"][tagName]["fields"] = newFields;
32+
var key = fields[fieldIndex].field;
33+
if( ! keys[key])
34+
{
35+
keys[key] = 1;
36+
newFields.push(fields[fieldIndex]);
37+
}
38+
} // for fieldIndex
39+
block["local"][tagName]["fields"][blockFieldKey] = newFields;
40+
} // for blockFieldKeysIndex
4641
}
4742
} // for blockIndex
4843
} // for fileIndex
49-
} // _postFilter
44+
} // postFilter
5045

5146
/**
5247
* Exports.
5348
*/
5449
module.exports = {
55-
postFilter: postFilter,
56-
_postFilter: _postFilter
50+
postFilter: postFilter
5751
};

‎lib/plugins/filter_api_success.js

+1-1
Original file line numberDiff line numberDiff line change
@@ -10,7 +10,7 @@ var filterApiParam = require("./filter_api_param.js");
1010
*/
1111
function postFilter(parsedFiles, filenames)
1212
{
13-
filterApiParam._postFilter(parsedFiles, filenames, "success");
13+
filterApiParam.postFilter(parsedFiles, filenames, "success");
1414
} // postFilter
1515

1616
/**

‎lib/plugins/parser_api_error.js

+7-2
Original file line numberDiff line numberDiff line change
@@ -1,15 +1,20 @@
11
// Same as @apiparam
22
var apiParam = require("./parser_api_param.js");
33

4+
function parse(content, source)
5+
{
6+
return apiParam.parse(content, source, "Error 4xx");
7+
}
8+
49
function pushTo()
510
{
6-
return "local.error.fields";
11+
return "local.error.fields." + apiParam.getGroup();
712
}
813

914
/**
1015
* Exports.
1116
*/
1217
module.exports = {
13-
parse: apiParam.parse,
18+
parse: parse,
1419
pushTo: pushTo
1520
};

‎lib/plugins/parser_api_error_title.js

+21
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
var apiParser = require("./parser_api_param_title.js");
2+
3+
function parse(content, source)
4+
{
5+
return apiParser.parse(content, source);
6+
} // parse
7+
8+
function pushTo()
9+
{
10+
return "global.errorTitle";
11+
}
12+
13+
/**
14+
* Exports.
15+
*/
16+
module.exports = {
17+
parse: parse,
18+
pushTo: pushTo,
19+
getGroup: apiParser.getGroup,
20+
allowMultiple: true
21+
};

‎lib/plugins/parser_api_info.js

+7-2
Original file line numberDiff line numberDiff line change
@@ -1,15 +1,20 @@
11
// Same as @apiparam
22
var apiParam = require("./parser_api_param.js");
33

4+
function parse(content, source)
5+
{
6+
return apiParam.parse(content, source, "Info");
7+
}
8+
49
function pushTo()
510
{
6-
return "local.info.fields";
11+
return "local.info.fields." + apiParam.getGroup();
712
}
813

914
/**
1015
* Exports.
1116
*/
1217
module.exports = {
13-
parse: apiParam.parse,
18+
parse: parse,
1419
pushTo: pushTo
1520
};

‎lib/plugins/parser_api_info_title.js

+21
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
var apiParser = require("./parser_api_param_title.js");
2+
3+
function parse(content, source)
4+
{
5+
return apiParser.parse(content, source);
6+
} // parse
7+
8+
function pushTo()
9+
{
10+
return "global.infoTitle";
11+
}
12+
13+
/**
14+
* Exports.
15+
*/
16+
module.exports = {
17+
parse: parse,
18+
pushTo: pushTo,
19+
getGroup: apiParser.getGroup,
20+
allowMultiple: true
21+
};

‎lib/plugins/parser_api_param.js

+27-12
Original file line numberDiff line numberDiff line change
@@ -1,16 +1,23 @@
1-
function parse(content)
1+
var group = "";
2+
3+
function parse(content, source, defaultGroup)
24
{
35
// Trim
46
content = content.replace(/^\s+|\s+$/g, "");
57

68
// Replace Linebreak with Unicode
79
content = content.replace(/\n/g, "\uffff");
810

9-
// Search: type, field, defaultValue, optional, description
11+
// Search: group, type, field, defaultValue, optional, description
1012
// Example: {Boolean} [user.name="Default Value"] Users lastname.
1113
// RegExp:
1214
// ^
1315
// (?:
16+
// (?:\(
17+
// (.+?) ; group
18+
// \))
19+
// \s*)?
20+
// (?:
1421
// (?:\{
1522
// (.+?) ; type
1623
// \})
@@ -24,8 +31,7 @@ function parse(content)
2431
// \s*
2532
// (.*)? ; description
2633
// (^@|$) ; Multiline
27-
//var parseRegExp = /^(?:(?:\{(.+?)\})\s*)?(\[?(\S[a-zA-Z0-9._\-]*)(?:=['|"]?([\s.a-zA-Z0-9_\-]*)['|"]?)?\]?)\s*(.*)?$/g;
28-
var parseRegExp = /^(?:(?:\{(.+?)\})\s*)?(\[?(\S[a-zA-Z0-9._\-]*)(?:=['|"]?([\s.a-zA-Z0-9_\-]*)['|"]?)?\]?)\s*(.*)?(^@|$)/g;
34+
var parseRegExp = /^(?:(?:\((.+?)\))\s*)?(?:(?:\{(.+?)\})\s*)?(\[?(\S[a-zA-Z0-9._\-]*)(?:=['|"]?([\s.a-zA-Z0-9_\-]*)['|"]?)?\]?)\s*(.*)?(^@|$)/g;
2935
var matches = parseRegExp.exec(content);
3036
// function objectValuesToString(obj)
3137
// {
@@ -67,26 +73,35 @@ function parse(content)
6773
if( ! matches) return null;
6874

6975
// Reverse Unicode Linebreaks
70-
if(matches[5]) matches[5] = matches[5].replace(/\uffff/g, "\n");
76+
if(matches[6]) matches[6] = matches[6].replace(/\uffff/g, "\n");
77+
78+
group = matches[1] || defaultGroup || "Parameter";
7179

7280
return {
73-
type: matches[1],
74-
field: matches[3],
75-
defaultValue: matches[4],
76-
optional: (matches[2] !== matches[3]) ? true : false,
77-
description: matches[5]
81+
group: group,
82+
type: matches[2],
83+
field: matches[4],
84+
defaultValue: matches[5],
85+
optional: (matches[3] !== matches[4]) ? true : false,
86+
description: matches[6] || ""
7887
};
7988
} // parse
8089

8190
function pushTo()
8291
{
83-
return "local.parameter.fields";
92+
return "local.parameter.fields." + getGroup();
93+
}
94+
95+
function getGroup()
96+
{
97+
return group;
8498
}
8599

86100
/**
87101
* Exports.
88102
*/
89103
module.exports = {
90104
parse: parse,
91-
pushTo: pushTo
105+
pushTo: pushTo,
106+
getGroup: getGroup
92107
};

0 commit comments

Comments
 (0)