Implement apiBody and apiQuery tags

lib/index.js

@@ -61,6 +61,8 @@ var app = {
     },
     parsers: {
         api                      : './parsers/api.js',
+        apibody                  : './parsers/api_body.js',
+        apiquery                 : './parsers/api_query.js',
         apidefine                : './parsers/api_define.js',
         apidescription           : './parsers/api_description.js',
         apierror                 : './parsers/api_error.js',

lib/parsers/api_body.js

@@ -0,0 +1,16 @@
+// Same as @apiParam
+var apiParser = require('./api_param.js');
+
+function parse(content, source) {
+    return apiParser.parse(content, source, 'Body');
+}
+
+/**
+ * Exports
+ */
+module.exports = {
+    parse         : parse,
+    path          : 'local.body',
+    method        : apiParser.method,
+    markdownFields: [ 'description' ]
+};

lib/parsers/api_query.js

@@ -0,0 +1,16 @@
+// Same as @apiParam
+var apiParser = require('./api_param.js');
+
+function parse(content, source) {
+    return apiParser.parse(content, source, 'Query');
+}
+
+/**
+ * Exports
+ */
+module.exports = {
+    parse         : parse,
+    path          : 'local.query',
+    method        : apiParser.method,
+    markdownFields: [ 'description' ]
+};

lib/workers/api_body_title.js

@@ -0,0 +1,42 @@
+var apiWorker = require('./api_param_title.js');
+
+// Additional information for error log
+var _messages = {
+    common: {
+        element: 'apiBody',
+        usage  : '@apiBody (group) varname',
+        example: '@apiDefine MyValidParamGroup Some title\n@apiBody (MyValidParamGroup) username'
+    }
+};
+
+/**
+ * PreProcess
+ *
+ * @param {Object[]} parsedFiles
+ * @param {String[]} filenames
+ * @param {Object}   packageInfos
+ * @returns {Object}
+ */
+function preProcess(parsedFiles, filenames, packageInfos) {
+    return apiWorker.preProcess(parsedFiles, filenames, packageInfos, 'defineBodyTitle');
+}
+
+/**
+ * PostProcess
+ *
+ * @param {Object[]} parsedFiles
+ * @param {String[]} filenames
+ * @param {Object[]} preProcess
+ * @param {Object}   packageInfos
+ */
+function postProcess(parsedFiles, filenames, preProcess, packageInfos) {
+    apiWorker.postProcess(parsedFiles, filenames, preProcess, packageInfos, 'defineBodyTitle', 'body', _messages);
+}
+
+/**
+ * Exports
+ */
+module.exports = {
+    preProcess : preProcess,
+    postProcess: postProcess
+};

lib/workers/api_query_title.js

@@ -0,0 +1,42 @@
+var apiWorker = require('./api_param_title.js');
+
+// Additional information for error log
+var _messages = {
+    common: {
+        element: 'apiQuery',
+        usage  : '@apiQuery (group) varname',
+        example: '@apiDefine MyValidParamGroup Some title\n@apiQuery (MyValidParamGroup) username'
+    }
+};
+
+/**
+ * PreProcess
+ *
+ * @param {Object[]} parsedFiles
+ * @param {String[]} filenames
+ * @param {Object}   packageInfos
+ * @returns {Object}
+ */
+function preProcess(parsedFiles, filenames, packageInfos) {
+    return apiWorker.preProcess(parsedFiles, filenames, packageInfos, 'defineQueryTitle');
+}
+
+/**
+ * PostProcess
+ *
+ * @param {Object[]} parsedFiles
+ * @param {String[]} filenames
+ * @param {Object[]} preProcess
+ * @param {Object}   packageInfos
+ */
+function postProcess(parsedFiles, filenames, preProcess, packageInfos) {
+    apiWorker.postProcess(parsedFiles, filenames, preProcess, packageInfos, 'defineQueryTitle', 'query', _messages);
+}
+
+/**
+ * Exports
+ */
+module.exports = {
+    preProcess : preProcess,
+    postProcess: postProcess
+};

test/parser_api_body_test.js

@@ -0,0 +1,130 @@
+/*jshint unused:false*/
+
+/**
+ * Test: Parser apiParam
+ */
+
+// node modules
+var should = require('should');
+
+// lib modules
+var parser = require('../lib/parsers/api_body');
+
+describe('Parser: apiParam', function() {
+
+    // TODO: Add 1.000 more possible cases ;-)
+    var testCases = [
+        {
+            title: 'Simple fieldname only',
+            content: 'simple',
+            expected: {
+                group: 'Body',
+                type: undefined,
+                size: undefined,
+                allowedValues: undefined,
+                optional: false,
+                field: 'simple',
+                defaultValue: undefined,
+                description: ''
+            }
+        },
+        {
+            title: 'Type, Fieldname, Description',
+            content: '{String} name The users name.',
+            expected: {
+                group: 'Body',
+                type: 'String',
+                size: undefined,
+                allowedValues: undefined,
+                optional: false,
+                field: 'name',
+                defaultValue: undefined,
+                description: 'The users name.'
+            }
+        },
+        {
+            title: 'Type, Fieldname, Description',
+            content: '{String|String[]} name The users name.',
+            expected: {
+                group: 'Body',
+                type: 'String|String[]',
+                size: undefined,
+                allowedValues: undefined,
+                optional: false,
+                field: 'name',
+                defaultValue: undefined,
+                description: 'The users name.'
+            }
+        },
+        {
+            title: '$Simple fieldname only',
+            content: '$simple',
+            expected: {
+                group: 'Body',
+                type: undefined,
+                size: undefined,
+                allowedValues: undefined,
+                optional: false,
+                field: '$simple',
+                defaultValue: undefined,
+                description: ''
+            }
+        },
+        {
+            title: 'All options, with optional defaultValue',
+            content: ' ( MyGroup ) { \\Object\\String.uni-code_char[] { 1..10 } = \'abc\', \'def\' }  ' +
+                     '[ \\MyClass\\field.user_first-name = \'John Doe\' ] Some description.',
+            expected: {
+                group: 'MyGroup',
+                type: '\\Object\\String.uni-code_char[]',
+                size: '1..10',
+                allowedValues: [ '\'abc\'', '\'def\'' ],
+                optional: true,
+                field: '\\MyClass\\field.user_first-name',
+                defaultValue: 'John Doe',
+                description: 'Some description.'
+            }
+        },
+        {
+            title: 'All options, without optional-marker',
+            content: ' ( MyGroup ) { \\Object\\String.uni-code_char[] { 1..10 } = \'abc\', \'def\' }  ' +
+                     '\\MyClass\\field.user_first-name = \'John Doe\' Some description.',
+            expected: {
+                group: 'MyGroup',
+                type: '\\Object\\String.uni-code_char[]',
+                size: '1..10',
+                allowedValues: [ '\'abc\'', '\'def\'' ],
+                optional: false,
+                field: '\\MyClass\\field.user_first-name',
+                defaultValue: 'John Doe',
+                description: 'Some description.'
+            }
+        },
+        {
+            title: 'All options, without optional-marker, without default value quotes',
+            content: ' ( MyGroup ) { \\Object\\String.uni-code_char[] { 1..10 } = \'abc\', \'def\' }  ' +
+                     '\\MyClass\\field.user_first-name = John_Doe Some description.',
+            expected: {
+                group: 'MyGroup',
+                type: '\\Object\\String.uni-code_char[]',
+                size: '1..10',
+                allowedValues: [ '\'abc\'', '\'def\'' ],
+                optional: false,
+                field: '\\MyClass\\field.user_first-name',
+                defaultValue: 'John_Doe',
+                description: 'Some description.'
+            }
+        },
+    ];
+
+    // create
+    it('case 1: should pass all regexp test cases', function(done) {
+        testCases.forEach(function(testCase) {
+            var parsed = parser.parse(testCase.content);
+            (parsed !== null).should.equal(true, 'Title: ' + testCase.title + ', Source: ' + testCase.content);
+            parsed.should.eql(testCase.expected);
+        });
+        done();
+    });
+
+});

test/parser_api_query_test.js

@@ -0,0 +1,86 @@
+/*jshint unused:false*/
+
+/**
+ * Test: Parser apiParam
+ */
+
+// node modules
+var should = require('should');
+
+// lib modules
+var parser = require('../lib/parsers/api_query');
+
+describe('Parser: apiQuery', function() {
+
+    // TODO: Add 1.000 more possible cases ;-)
+    var testCases = [
+        {
+            title: 'Type, Fieldname, Description',
+            content: '{String} name The users name.',
+            expected: {
+                group: 'Query',
+                type: 'String',
+                size: undefined,
+                allowedValues: undefined,
+                optional: false,
+                field: 'name',
+                defaultValue: undefined,
+                description: 'The users name.'
+            }
+        },
+        {
+            title: 'Type, Fieldname, Description',
+            content: '{String|String[]} name The users name.',
+            expected: {
+                group: 'Query',
+                type: 'String|String[]',
+                size: undefined,
+                allowedValues: undefined,
+                optional: false,
+                field: 'name',
+                defaultValue: undefined,
+                description: 'The users name.'
+            }
+        },
+        {
+            title: '$Simple fieldname only',
+            content: '$simple',
+            expected: {
+                group: 'Query',
+                type: undefined,
+                size: undefined,
+                allowedValues: undefined,
+                optional: false,
+                field: '$simple',
+                defaultValue: undefined,
+                description: ''
+            }
+        },
+        {
+            title: 'All options, with optional defaultValue',
+            content: ' ( MyGroup ) { \\Object\\String.uni-code_char[] { 1..10 } = \'abc\', \'def\' }  ' +
+                     '[ \\MyClass\\field.user_first-name = \'John Doe\' ] Some description.',
+            expected: {
+                group: 'MyGroup',
+                type: '\\Object\\String.uni-code_char[]',
+                size: '1..10',
+                allowedValues: [ '\'abc\'', '\'def\'' ],
+                optional: true,
+                field: '\\MyClass\\field.user_first-name',
+                defaultValue: 'John Doe',
+                description: 'Some description.'
+            }
+        },
+    ];
+
+    // create
+    it('case 1: should pass all regexp test cases', function(done) {
+        testCases.forEach(function(testCase) {
+            var parsed = parser.parse(testCase.content);
+            (parsed !== null).should.equal(true, 'Title: ' + testCase.title + ', Source: ' + testCase.content);
+            parsed.should.eql(testCase.expected);
+        });
+        done();
+    });
+
+});