Bump version 0.8.0

CHANGELOG.md

@@ -45,12 +45,15 @@
   * Add debug output.
 
 * Parser
+  * Ignore other doc-language @-parameters (enables jsdoc, phpdoc, ... again).
+  * Add apidoc specification version to project file.
   * Correctly handle Erlang comments.
   * Bugfix: Markdown error on Empty description.
   * Revised worker preProcess / postProcess functions.
   * Change parser export names.
 
 * Template
+  * Show size and allowed values in field description.
   * Change template sample request to handle custom named groups.
   * Update template vendor files (handlebars 2, requirejs)
   * Added support for using path-to-regexp in sample request.

EXAMPLES.MD

@@ -0,0 +1,78 @@
+# apiDoc Examples
+
+Full documentation at [apidocjs.com](http://apidocjs.com).
+
+This file show some best practice hints and examples.
+
+
+
+## Define & use
+
+For a better readability in the source-code, it is recommended to use `@apiDefine` and `@apiUse` as less as possible.
+
+
+
+### Naming
+
+You should choose a consistent naming schema, which make it easier to understand what is defined and included.
+
+E.g. with `@apiUse LoginParam`, `@apiUse LoginError`, `@apiUse LoginSuccess` you see that parameter-, errors- and
+success-fields are classified with the suffix `Param`, `Error` and `Success`.
+
+
+
+### Example for parameter
+
+```js
+/**
+ * @apiDefine LoginParam
+ * @apiParam {String} username Your e-mail-address.
+ * @apiParam {String} password Your password.
+ */
+
+/**
+ * @apiDefine UserParam
+ * @apiParam {String} firstname Your firstname.
+ * @apiParam {String} lastname  Your lastname.
+ * @apiParam {Date}   birthday  Your birthday.
+ */
+
+/**
+ * @api {GET} /account/register Register a new user.
+ * @apiUse LoginParam
+ * @apiUse UserParam
+ * @apiParam {Boolean} terms Checkbox to accept the terms.
+ */
+
+/**
+ * @api {GET} /account/login Signin with an existing user.
+ * @apiUse LoginParam
+ * @apiParam {Boolean} rememberme Checkbox to auto-login on revisit.
+ */
+```
+Block 1 defines the `LoginParam` with 2 fields, which are required for register and login.
+Block 2 defines the `UserParam` with 3 fields, which are required only for register.
+Block 3 is the endpoint `/account/register`, which use parameters from `LoginParam`, `UserParam` and an extra checkbox.
+Block 4 is the endpoint `/account/login`, which use only parameters from `LoginParam` and an extra checkbox.
+
+
+
+### Example for a group
+
+```js
+/**
+ * @apiDefine AccountGroup Account endpoints
+ *
+ * Here is the description for the "AccountGroup".
+ * It can contain **markdown** syntax.
+ */
+
+/**
+ * @api {GET} /account/login Signin with an existing user.
+ * @apiGroup AccountGroup
+ */
+```
+Block 1 defines the `AccountGroup` with a title and a description (the following lines).
+Block 2 is the endpoint `/account/login`, which belong to the group `AccountGroup` and inherit from there the title and
+description.
+`@apiGroup name` only inherit the title and description, while `@apiUse` would inherit all defined fields in a block.

README.md

@@ -24,7 +24,7 @@ Documentation at [apidocjs.com](http://apidocjs.com).
 
 ## Example
 
-   ```javascript
+```javascript
 /**
  * @api {get} /user/:id Request User information
  * @apiName GetUser
@@ -35,13 +35,16 @@ Documentation at [apidocjs.com](http://apidocjs.com).
  * @apiSuccess {String} firstname Firstname of the User.
  * @apiSuccess {String} lastname  Lastname of the User.
  */
-   ```
+```
 
 `apidoc -i example/ -o doc/`
 
 Creates from input files in `example/` a documentation in path `doc/`.
 
 
+More examples and best practice hints: [EXAMPLES.md](https://github.com/apidoc/apidoc/blob/master/EXAMPLES.md)
+
+
 ## Supported programming languages
 
  * **C#, Go, Dart, Java, JavaScript, PHP** (all DocStyle capable languages):
@@ -106,7 +109,8 @@ Creates from input files in `example/` a documentation in path `doc/`.
 
 ## Help
 
-Please add [issues](https://github.com/apidoc/apidoc/issues) if you have a question or found a problem. Pull requests are welcome too!
+Please add [issues](https://github.com/apidoc/apidoc/issues) if you have a question or found a problem.
+Pull requests are welcome too!
 
 A chat about apiDoc is on [Gitter](https://gitter.im/apidoc/talk).
 

lib/apidoc.js

@@ -12,6 +12,9 @@ var ParameterError = require('./errors/parameter_error');
 var ParserError = require('./errors/parser_error');
 var WorkerError = require('./errors/worker_error');
 
+// const
+var APIDOC_SPECIFICATION_VERSION = '0.2.0';
+
 // Options
 var _defaultOptions = {
     excludeFilters: [],
@@ -260,6 +263,10 @@ function createOutputFiles(blocks, packageInfos) {
     var apiData = JSON.stringify(blocks, null, 2);
     apiData = apiData.replace(/(\r\n|\n|\r)/g, '\r\n');
 
+    // add apiDoc specification version
+    packageInfos.apidoc = APIDOC_SPECIFICATION_VERSION;
+
+    // api_project
     var apiProject = JSON.stringify(packageInfos, null, 2);
     apiProject = apiProject.replace(/(\r\n|\n|\r)/g, '\r\n');
 

lib/parser.js

@@ -211,7 +211,7 @@ Parser.prototype._parseBlockElements = function(indexApiBlocks, detectedElements
                         if (values[markdownField]) {
                             values[markdownField] = markdown(values[markdownField]);
                             // remove line breaks
-                            values[markdownField] = values[markdownField].replace(/(\r\n|\n|\r)/g, '');
+                            values[markdownField] = values[markdownField].replace(/(\r\n|\n|\r)/g, ' ');
                         }
                     }
                 }

lib/parsers/api.js

@@ -4,7 +4,7 @@ function parse(content) {
 
     // Search: type, url and title
     // Example: {get} /user/:id Get User by ID.
-    var parseRegExp = /^(?:(?:\{(.+?)\})?\s)?(.+?)(?:\s(.+?))?$/g;
+    var parseRegExp = /^(?:(?:\{(.+?)\})?\s*)?(.+?)(?:\s+(.+?))?$/g;
     var matches = parseRegExp.exec(content);
 
     if ( ! matches)

lib/parsers/api_define_permission.js

@@ -5,8 +5,8 @@ var apiParser = require('./api_define.js');
 var _messages = {
     common: {
         element: 'apiDefinePermission',
-        usage  : '@apiDdefinePermission name',
-        example: '@apiDdefinePermission MyValidPermissionName'
+        usage  : '@apiDefinePermission name',
+        example: '@apiDefinePermission MyValidPermissionName'
     }
 };
 
@@ -19,7 +19,7 @@ function parse(content, source) {
  */
 module.exports = {
     parse         : parse,
-    path          : 'global.definePermission',
+    path          : 'global.define',
     method        : apiParser.method,
     markdownFields: [ 'description' ],
     deprecated    : true,

lib/parsers/api_param.js

@@ -33,7 +33,7 @@ var regExp = {
     },
     wName: {
         b:               '(\\[?\\s*',                       // 5 optional optional-marker
-        name:                '([a-zA-Z0-9\\.\\/\\\\\\[\\]_-]+)', // 6
+        name:                '([a-zA-Z0-9\\.\\/\\\\_-]+)', // 6
         oDefaultValue: {                                    // optional defaultValue
             b:               '(?:\\s*=\\s*(?:',             // starting with '=', optional surrounding spaces
             withDoubleQuote:     '"([^"]*)"',               // 7
@@ -60,9 +60,9 @@ function _objectValuesToString(obj) {
 
 var parseRegExp = new RegExp(_objectValuesToString(regExp));
 
-var allowedValuesWithDoubleQuoteRegExp = new RegExp(/\"[^\"]*[^\"]\'/g);
+var allowedValuesWithDoubleQuoteRegExp = new RegExp(/\"[^\"]*[^\"]\"/g);
 var allowedValuesWithQuoteRegExp = new RegExp(/\'[^\']*[^\']\'/g);
-var allowedValuesRegExp = new RegExp(/[^,\s]/g);
+var allowedValuesRegExp = new RegExp(/[^,\s]+/g);
 
 function parse(content, source, defaultGroup) {
     // trim
@@ -79,20 +79,18 @@ function parse(content, source, defaultGroup) {
     var allowedValues = matches[4];
     if (allowedValues) {
         var regExp;
-        if (allowedValues[0] === '"')
+        if (allowedValues.charAt(0) === '"')
             regExp = allowedValuesWithDoubleQuoteRegExp;
-        else if (allowedValues[0] === '\'')
+        else if (allowedValues.charAt(0) === '\'')
             regExp = allowedValuesWithQuoteRegExp;
         else
             regExp = allowedValuesRegExp;
 
         var allowedValuesMatch;
         var list = [];
+
         while (allowedValuesMatch = regExp.exec(allowedValues)) {
-            if (typeof allowedValuesMatch === 'string')
-                list.push(allowedValuesMatch);
-            else
-                list.push(allowedValuesMatch[0]);
+            list.push(allowedValuesMatch[0]);
         }
         allowedValues = list;
     }

lib/workers/api_error_structure.js

@@ -27,11 +27,11 @@ function preProcess(parsedFiles, filenames, packageInfos) {
  *
  * @param {Object[]} parsedFiles
  * @param {String[]} filenames
- * @param {Object[]} preProcessResults
+ * @param {Object[]} preProcess
  * @param {Object}   packageInfos
  */
-function postProcess(parsedFiles, filenames, preProcessResults, packageInfos) {
-    apiWorker.postProcess(parsedFiles, filenames, preProcessResults, packageInfos, 'defineErrorStructure', 'errorStructure', _messages);
+function postProcess(parsedFiles, filenames, preProcess, packageInfos) {
+    apiWorker.postProcess(parsedFiles, filenames, preProcess, packageInfos, 'defineErrorStructure', 'errorStructure', _messages);
 }
 
 /**

lib/workers/api_error_title.js

@@ -27,11 +27,11 @@ function preProcess(parsedFiles, filenames, packageInfos) {
  *
  * @param {Object[]} parsedFiles
  * @param {String[]} filenames
- * @param {Object[]} preProcessResults
+ * @param {Object[]} preProcess
  * @param {Object}   packageInfos
  */
-function postProcess(parsedFiles, filenames, preProcessResults, packageInfos) {
-    apiWorker.postProcess(parsedFiles, filenames, preProcessResults, packageInfos, 'defineErrorTitle', 'error', _messages);
+function postProcess(parsedFiles, filenames, preProcess, packageInfos) {
+    apiWorker.postProcess(parsedFiles, filenames, preProcess, packageInfos, 'defineErrorTitle', 'error', _messages);
 }
 
 /**