Permalink
Browse files

Bump version 0.8.0

  • Loading branch information...
1 parent 765e23f commit 62767953b760a3efc61034487347fd95a778b575 @rottmann rottmann committed Nov 17, 2014
View
@@ -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.
View
@@ -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.
View
@@ -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).
View
@@ -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');
View
@@ -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, ' ');
}
}
}
View
@@ -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)
@@ -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,
@@ -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;
}
@@ -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);
}
/**
@@ -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);
}
/**
Oops, something went wrong.

0 comments on commit 6276795

Please sign in to comment.