From b531ec0abef67dc04cc7d3a494bb389d239f2a35 Mon Sep 17 00:00:00 2001 From: Peter Rottmann Date: Tue, 4 Mar 2014 17:31:48 +0100 Subject: [PATCH] Add language test cases. --- CHANGELOG.md | 10 ++ Gruntfile.js | 2 +- README.md | 35 +++++- bin/apidoc | 2 +- lib/apidoc.js | 2 +- lib/parser.js | 39 ++++++- test/fixtures/api_data.js | 168 +++++++++++++++++++++++++++- test/fixtures/api_data.json | 168 +++++++++++++++++++++++++++- test/fixtures/api_project.js | 6 +- test/fixtures/api_project.json | 6 +- test/fixtures/example/language.erl | 35 ++++++ test/fixtures/example/language.erl~ | 0 test/fixtures/example/language.js | 35 ++++++ test/fixtures/example/language.py | 35 ++++++ test/fixtures/example/language.rb | 35 ++++++ 15 files changed, 554 insertions(+), 24 deletions(-) create mode 100644 test/fixtures/example/language.erl create mode 100644 test/fixtures/example/language.erl~ create mode 100644 test/fixtures/example/language.js create mode 100644 test/fixtures/example/language.py create mode 100644 test/fixtures/example/language.rb diff --git a/CHANGELOG.md b/CHANGELOG.md index 74484eb2..d46ad7e3 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,5 +1,15 @@ # apiDoc Changelog +#### 0.4.0 +Add support for other comment-style. Now apiDoc supports: + * Erlang + * JavaScript (DocStyle: e.g. also used C#, Go, Dart, Java, PHP) + * Python + * Ruby +Add some programming language test cases. +Remove german code comments. +Upgrade all used node modules. + #### 0.3.0 Replace deprecated node-markdown with [marked](https://github.com/chjj/marked). Add cli parameter for marked `--marked-...`, watch all params with`--help`. diff --git a/Gruntfile.js b/Gruntfile.js index 21ae5a57..d7bb1070 100644 --- a/Gruntfile.js +++ b/Gruntfile.js @@ -23,7 +23,7 @@ module.exports = function(grunt) }, // clean jshint: { - all: ["Gruntfile.js", "lib/**/*.js", "test/**/*.js"], + all: ["Gruntfile.js", "lib/**/*.js", "test/**/*.js", "!test/fixtures/**"], options: { // Enforcing Options bitwise: true, diff --git a/README.md b/README.md index 0e1759eb..fd42d414 100644 --- a/README.md +++ b/README.md @@ -1,4 +1,4 @@ -# apiDoc 0.3.0 +# apiDoc 0.4.0 Generates a RESTful web API Documentation. @@ -6,6 +6,39 @@ Documentation at [apidocjs.com](http://apidocjs.com). [Example](http://apidocjs.com/example/) output. +## Supported programming languages + + * **C#, Go, Dart, Java, JavaScript, PHP** (all DocStyle capable languages like ): + + ```javascript + /** + * This is a comment. + */ + ``` + + * **Erlang**: + + ```erlang + %{ + This is a comment. + %} + ``` + + * **Python** + + ```python + """ + This is a comment. + """ + ``` + + * **Ruby** + + ```ruby + =begin + This is a comment. + =end + ``` ## Installation diff --git a/bin/apidoc b/bin/apidoc index b4333748..ec581508 100755 --- a/bin/apidoc +++ b/bin/apidoc @@ -19,7 +19,7 @@ var argv = optimist .option("f", { alias: "file-filters", - "default": ".*\\.js$", + "default": ".*\\.(cs|dart|erl|go|java|js|php?|py|rb|ts)$", describe: "RegEx-Filter to select files that should be parsed (multiple -f can be used)." }) diff --git a/lib/apidoc.js b/lib/apidoc.js index 05d9a1a8..38e404e8 100644 --- a/lib/apidoc.js +++ b/lib/apidoc.js @@ -14,7 +14,7 @@ var colors = require("colors"); // Options var _defaultOptions = { excludeFilters: [], - includeFilters: [ ".*\\.js$" ], + includeFilters: [ ".*\\.(cs|dart|erl|go|java|js|php?|py|rb|ts)$" ], src: path.join(__dirname, "../example/"), dest: path.join(__dirname, "../doc/"), diff --git a/lib/parser.js b/lib/parser.js index 0020cae8..ba88ff6f 100644 --- a/lib/parser.js +++ b/lib/parser.js @@ -1,4 +1,5 @@ var fs = require("fs"); +var path = require("path"); var util = require("util"); var _ = require("underscore"); @@ -53,6 +54,7 @@ Parser.prototype.parseFile = function(filename) app.debug("inspect file: " + filename); self.filename = filename; + self.extension = path.extname(filename).toLowerCase(); self.src = fs.readFileSync(filename, "utf8").toString(); app.debug("size: " + self.src.length); @@ -263,16 +265,41 @@ Parser.prototype._findBlocks = function() var self = this; var blocks = []; var src = self.src; + var inlineRegExp; + var docBlocksRegExp; // Replace Linebreak with Unicode src = src.replace(/\n/g, "\uffff"); - // Remove not needed " * " and " " (tab) at the beginning - //var starsRegExp = /^\s?(\*|\s)?\s?/gm; - var starsRegExp = /^(\s+)?(\*|\s)[ ]?/gm; + // Blocksearch depending on file-extension + switch(self.extension) + { + case ".erl": + // Find document blocks between "%{" and "%}" + docBlocksRegExp = /\%\{\uffff(.+?)\%\}/g; + // Remove not needed " % " and " " (tabs) at the beginning + // HINT: Not sure if erlang developer use the %, but i think it should be no problem + inlineRegExp = /^(\t+)?(\%)[ ]?/gm; + break; + case ".py": + // Find document blocks between """ and """ + docBlocksRegExp = /\"\"\"\uffff(.+?)\"\"\"/g; + // Remove not needed " " (tabs) at the beginning + inlineRegExp = /^(\t+)?[ ]?/gm; + break; + case ".rb": + // Find document blocks between "=begin" and "=end" + docBlocksRegExp = /\=begin\uffff(.+?)\=end/g; + // Remove not needed " " (tabs) at the beginning + inlineRegExp = /^(\t+)?[ ]?/gm; + break; + default: + // Find document blocks between "/**" and "*/" + docBlocksRegExp = /\/\*\*\uffff(.+?)\*\//g; + // Remove not needed " * " and " " (tabs) at the beginning + inlineRegExp = /^(\s+)?(\*)[ ]?/gm; + } // switch - // Find documentsblocks between "/**" and "*/" - var docBlocksRegExp = /\/\*\*\uffff(.+?)\*\//g; var matches = docBlocksRegExp.exec(src); while(matches) { @@ -281,7 +308,7 @@ Parser.prototype._findBlocks = function() // Reverse Unicode Linebreaks block = block.replace(/\uffff/g, "\n"); - block = block.replace(starsRegExp, ""); + block = block.replace(inlineRegExp, ""); blocks.push(block); diff --git a/test/fixtures/api_data.js b/test/fixtures/api_data.js index b6500708..e3145454 100644 --- a/test/fixtures/api_data.js +++ b/test/fixtures/api_data.js @@ -174,6 +174,166 @@ define({ api: [ }, "filename": "test/fixtures/example/_grouping.js" }, + { + "type": "get", + "url": "/language/erlang", + "title": "Erlang", + "name": "GetLanguageErlang", + "group": "Language", + "version": "0.4.0", + "description": "Test for Erlang Comment-Syntax.", + "filename": "test/fixtures/example/language.erl" + }, + { + "type": "get", + "url": "/language/erlang/indented1", + "title": "Erlang indented 1", + "name": "GetLanguageErlangIndented1", + "group": "Language", + "version": "0.4.0", + "examples": [ + { + "title": "Test for indented comment.", + "content": "This is example line 2.\nThis is example line 3.\n\t Line 4 indented (with tab at beginning).\n Line 5 indented.\nThis is example line 6.\n" + } + ], + "filename": "test/fixtures/example/language.erl" + }, + { + "type": "get", + "url": "/language/erlang/indented2", + "title": "Erlang indented 2", + "name": "GetLanguageErlangIndented2", + "group": "Language", + "version": "0.4.0", + "examples": [ + { + "title": "Test for indented comment.", + "content": "This is example line 2.\nThis is example line 3.\n Line 4 indented (with tab at beginning).\n Line 5 indented.\nThis is example line 6.\n" + } + ], + "filename": "test/fixtures/example/language.erl" + }, + { + "type": "get", + "url": "/language/javascript", + "title": "JavaScript", + "name": "GetLanguageJavaScript", + "group": "Language", + "version": "0.4.0", + "description": "Test for JavaScript Comment-Syntax.", + "filename": "test/fixtures/example/language.js" + }, + { + "type": "get", + "url": "/language/javascript/indented1", + "title": "JavaScript indented 1", + "name": "GetLanguageJavaScriptIndented1", + "group": "Language", + "version": "0.4.0", + "examples": [ + { + "title": "Test for indented comment.", + "content": "This is example line 2.\nThis is example line 3.\n Line 4 indented (with tab at beginning).\n Line 5 indented.\nThis is example line 6.\n" + } + ], + "filename": "test/fixtures/example/language.js" + }, + { + "type": "get", + "url": "/language/javascript/indented2", + "title": "JavaScript indented 2", + "name": "GetLanguageJavaScriptIndented2", + "group": "Language", + "version": "0.4.0", + "examples": [ + { + "title": "Test for indented comment.", + "content": "This is example line 2.\nThis is example line 3.\n Line 4 indented (with tab at beginning).\n Line 5 indented.\nThis is example line 6.\n" + } + ], + "filename": "test/fixtures/example/language.js" + }, + { + "type": "get", + "url": "/language/python", + "title": "Python", + "name": "GetLanguagePython", + "group": "Language", + "version": "0.4.0", + "description": "Test for Python Comment-Syntax.", + "filename": "test/fixtures/example/language.py" + }, + { + "type": "get", + "url": "/language/python/indented1", + "title": "Python indented 1", + "name": "GetLanguagePythonIndented1", + "group": "Language", + "version": "0.4.0", + "examples": [ + { + "title": "Test for indented comment.", + "content": "This is example line 2.\nThis is example line 3.\n Line 4 indented (with tab at beginning).\n Line 5 indented.\nThis is example line 6.\n" + } + ], + "filename": "test/fixtures/example/language.py" + }, + { + "type": "get", + "url": "/language/python/indented2", + "title": "Python indented 2", + "name": "GetLanguagePythonIndented2", + "group": "Language", + "version": "0.4.0", + "examples": [ + { + "title": "Test for indented comment.", + "content": "This is example line 2.\nThis is example line 3.\n Line 4 indented (with tab at beginning).\n Line 5 indented.\nThis is example line 6.\n" + } + ], + "filename": "test/fixtures/example/language.py" + }, + { + "type": "get", + "url": "/language/ruby", + "title": "Ruby", + "name": "GetLanguageRuby", + "group": "Language", + "version": "0.4.0", + "description": "Test for Ruby Comment-Syntax.", + "filename": "test/fixtures/example/language.rb" + }, + { + "type": "get", + "url": "/language/ruby/indented1", + "title": "Ruby indented 1", + "name": "GetLanguageRubyIndented1", + "group": "Language", + "version": "0.4.0", + "examples": [ + { + "title": "Test for indented comment.", + "content": "This is example line 2.\nThis is example line 3.\n Line 4 indented (with tab at beginning).\n Line 5 indented.\nThis is example line 6.\n" + } + ], + "filename": "test/fixtures/example/language.rb" + }, + { + "type": "get", + "url": "/language/ruby/indented2", + "title": "Ruby indented 2", + "name": "GetLanguageRubyIndented2", + "group": "Language", + "version": "0.4.0", + "examples": [ + { + "title": "Test for indented comment.", + "content": "This is example line 2.\nThis is example line 3.\n Line 4 indented (with tab at beginning).\n Line 5 indented.\nThis is example line 6.\n" + } + ], + "filename": "test/fixtures/example/language.rb" + }, { "type": "get", "url": "/param/:id", @@ -549,9 +709,9 @@ define({ api: [ "Parameter": [ { "group": "Parameter", - "field": "field1", + "field": "field2", "optional": false, - "description": "This is Field 1." + "description": "This is Field 2." } ] } @@ -568,9 +728,9 @@ define({ api: [ "Parameter": [ { "group": "Parameter", - "field": "field2", + "field": "field1", "optional": false, - "description": "This is Field 2." + "description": "This is Field 1." } ] } diff --git a/test/fixtures/api_data.json b/test/fixtures/api_data.json index f6668a95..2e2662cd 100644 --- a/test/fixtures/api_data.json +++ b/test/fixtures/api_data.json @@ -174,6 +174,166 @@ }, "filename": "test/fixtures/example/_grouping.js" }, + { + "type": "get", + "url": "/language/erlang", + "title": "Erlang", + "name": "GetLanguageErlang", + "group": "Language", + "version": "0.4.0", + "description": "Test for Erlang Comment-Syntax.", + "filename": "test/fixtures/example/language.erl" + }, + { + "type": "get", + "url": "/language/erlang/indented1", + "title": "Erlang indented 1", + "name": "GetLanguageErlangIndented1", + "group": "Language", + "version": "0.4.0", + "examples": [ + { + "title": "Test for indented comment.", + "content": "This is example line 2.\nThis is example line 3.\n\t Line 4 indented (with tab at beginning).\n Line 5 indented.\nThis is example line 6.\n" + } + ], + "filename": "test/fixtures/example/language.erl" + }, + { + "type": "get", + "url": "/language/erlang/indented2", + "title": "Erlang indented 2", + "name": "GetLanguageErlangIndented2", + "group": "Language", + "version": "0.4.0", + "examples": [ + { + "title": "Test for indented comment.", + "content": "This is example line 2.\nThis is example line 3.\n Line 4 indented (with tab at beginning).\n Line 5 indented.\nThis is example line 6.\n" + } + ], + "filename": "test/fixtures/example/language.erl" + }, + { + "type": "get", + "url": "/language/javascript", + "title": "JavaScript", + "name": "GetLanguageJavaScript", + "group": "Language", + "version": "0.4.0", + "description": "Test for JavaScript Comment-Syntax.", + "filename": "test/fixtures/example/language.js" + }, + { + "type": "get", + "url": "/language/javascript/indented1", + "title": "JavaScript indented 1", + "name": "GetLanguageJavaScriptIndented1", + "group": "Language", + "version": "0.4.0", + "examples": [ + { + "title": "Test for indented comment.", + "content": "This is example line 2.\nThis is example line 3.\n Line 4 indented (with tab at beginning).\n Line 5 indented.\nThis is example line 6.\n" + } + ], + "filename": "test/fixtures/example/language.js" + }, + { + "type": "get", + "url": "/language/javascript/indented2", + "title": "JavaScript indented 2", + "name": "GetLanguageJavaScriptIndented2", + "group": "Language", + "version": "0.4.0", + "examples": [ + { + "title": "Test for indented comment.", + "content": "This is example line 2.\nThis is example line 3.\n Line 4 indented (with tab at beginning).\n Line 5 indented.\nThis is example line 6.\n" + } + ], + "filename": "test/fixtures/example/language.js" + }, + { + "type": "get", + "url": "/language/python", + "title": "Python", + "name": "GetLanguagePython", + "group": "Language", + "version": "0.4.0", + "description": "Test for Python Comment-Syntax.", + "filename": "test/fixtures/example/language.py" + }, + { + "type": "get", + "url": "/language/python/indented1", + "title": "Python indented 1", + "name": "GetLanguagePythonIndented1", + "group": "Language", + "version": "0.4.0", + "examples": [ + { + "title": "Test for indented comment.", + "content": "This is example line 2.\nThis is example line 3.\n Line 4 indented (with tab at beginning).\n Line 5 indented.\nThis is example line 6.\n" + } + ], + "filename": "test/fixtures/example/language.py" + }, + { + "type": "get", + "url": "/language/python/indented2", + "title": "Python indented 2", + "name": "GetLanguagePythonIndented2", + "group": "Language", + "version": "0.4.0", + "examples": [ + { + "title": "Test for indented comment.", + "content": "This is example line 2.\nThis is example line 3.\n Line 4 indented (with tab at beginning).\n Line 5 indented.\nThis is example line 6.\n" + } + ], + "filename": "test/fixtures/example/language.py" + }, + { + "type": "get", + "url": "/language/ruby", + "title": "Ruby", + "name": "GetLanguageRuby", + "group": "Language", + "version": "0.4.0", + "description": "Test for Ruby Comment-Syntax.", + "filename": "test/fixtures/example/language.rb" + }, + { + "type": "get", + "url": "/language/ruby/indented1", + "title": "Ruby indented 1", + "name": "GetLanguageRubyIndented1", + "group": "Language", + "version": "0.4.0", + "examples": [ + { + "title": "Test for indented comment.", + "content": "This is example line 2.\nThis is example line 3.\n Line 4 indented (with tab at beginning).\n Line 5 indented.\nThis is example line 6.\n" + } + ], + "filename": "test/fixtures/example/language.rb" + }, + { + "type": "get", + "url": "/language/ruby/indented2", + "title": "Ruby indented 2", + "name": "GetLanguageRubyIndented2", + "group": "Language", + "version": "0.4.0", + "examples": [ + { + "title": "Test for indented comment.", + "content": "This is example line 2.\nThis is example line 3.\n Line 4 indented (with tab at beginning).\n Line 5 indented.\nThis is example line 6.\n" + } + ], + "filename": "test/fixtures/example/language.rb" + }, { "type": "get", "url": "/param/:id", @@ -549,9 +709,9 @@ "Parameter": [ { "group": "Parameter", - "field": "field1", + "field": "field2", "optional": false, - "description": "This is Field 1." + "description": "This is Field 2." } ] } @@ -568,9 +728,9 @@ "Parameter": [ { "group": "Parameter", - "field": "field2", + "field": "field1", "optional": false, - "description": "This is Field 2." + "description": "This is Field 1." } ] } diff --git a/test/fixtures/api_project.js b/test/fixtures/api_project.js index 039033bc..19cf2258 100644 --- a/test/fixtures/api_project.js +++ b/test/fixtures/api_project.js @@ -1,10 +1,10 @@ define({ "name": "apidoc", - "version": "0.3.0", + "version": "0.4.0", "description": "RESTful web API Documentation Generator", "apidoc": "", "generator": { - "version": "0.3.0", - "time": "2013-12-23T15:00:00.000Z" + "version": "0.4.0", + "time": "2014-03-04T16:24:51.514Z" } }); \ No newline at end of file diff --git a/test/fixtures/api_project.json b/test/fixtures/api_project.json index a76f7da5..ab87f8b4 100644 --- a/test/fixtures/api_project.json +++ b/test/fixtures/api_project.json @@ -1,10 +1,10 @@ { "name": "apidoc", - "version": "0.3.0", + "version": "0.4.0", "description": "RESTful web API Documentation Generator", "apidoc": "", "generator": { - "version": "0.3.0", - "time": "2013-12-23T15:00:00.000Z" + "version": "0.4.0", + "time": "2014-03-04T16:24:51.514Z" } } \ No newline at end of file diff --git a/test/fixtures/example/language.erl b/test/fixtures/example/language.erl new file mode 100644 index 00000000..fea418e9 --- /dev/null +++ b/test/fixtures/example/language.erl @@ -0,0 +1,35 @@ +% Test for programming language: Erlang + +%{ +@api {get} /language/erlang Erlang +@apiName GetLanguageErlang +@apiGroup Language +@apiVersion 0.4.0 +@apiDescription Test for Erlang Comment-Syntax. +%} + +%{ +% @api {get} /language/erlang/indented1 Erlang indented 1 +% @apiName GetLanguageErlangIndented1 +% @apiGroup Language +% @apiVersion 0.4.0 +% @apiExample Test for indented comment. +% This is example line 2. +% This is example line 3. +% Line 4 indented (with tab at beginning). +% Line 5 indented. +% This is example line 6. +%} + +%{ +@api {get} /language/erlang/indented2 Erlang indented 2 +@apiName GetLanguageErlangIndented2 +@apiGroup Language +@apiVersion 0.4.0 +@apiExample Test for indented comment. +This is example line 2. +This is example line 3. + Line 4 indented (with tab at beginning). + Line 5 indented. +This is example line 6. +%} diff --git a/test/fixtures/example/language.erl~ b/test/fixtures/example/language.erl~ new file mode 100644 index 00000000..e69de29b diff --git a/test/fixtures/example/language.js b/test/fixtures/example/language.js new file mode 100644 index 00000000..5408f581 --- /dev/null +++ b/test/fixtures/example/language.js @@ -0,0 +1,35 @@ +// Test for programming language: JavaScript + +/** + * @api {get} /language/javascript JavaScript + * @apiName GetLanguageJavaScript + * @apiGroup Language + * @apiVersion 0.4.0 + * @apiDescription Test for JavaScript Comment-Syntax. + */ + +/** + * @api {get} /language/javascript/indented1 JavaScript indented 1 + * @apiName GetLanguageJavaScriptIndented1 + * @apiGroup Language + * @apiVersion 0.4.0 + * @apiExample Test for indented comment. + * This is example line 2. + * This is example line 3. + * Line 4 indented (with tab at beginning). + * Line 5 indented. + * This is example line 6. + */ + +/** +@api {get} /language/javascript/indented2 JavaScript indented 2 +@apiName GetLanguageJavaScriptIndented2 +@apiGroup Language +@apiVersion 0.4.0 +@apiExample Test for indented comment. +This is example line 2. +This is example line 3. + Line 4 indented (with tab at beginning). + Line 5 indented. +This is example line 6. +*/ diff --git a/test/fixtures/example/language.py b/test/fixtures/example/language.py new file mode 100644 index 00000000..3fcdcdac --- /dev/null +++ b/test/fixtures/example/language.py @@ -0,0 +1,35 @@ +# Test for programming language: Python + +""" +@api {get} /language/python Python +@apiName GetLanguagePython +@apiGroup Language +@apiVersion 0.4.0 +@apiDescription Test for Python Comment-Syntax. +""" + +""" + @api {get} /language/python/indented1 Python indented 1 + @apiName GetLanguagePythonIndented1 + @apiGroup Language + @apiVersion 0.4.0 + @apiExample Test for indented comment. + This is example line 2. + This is example line 3. + Line 4 indented (with tab at beginning). + Line 5 indented. + This is example line 6. +""" + +""" +@api {get} /language/python/indented2 Python indented 2 +@apiName GetLanguagePythonIndented2 +@apiGroup Language +@apiVersion 0.4.0 +@apiExample Test for indented comment. +This is example line 2. +This is example line 3. + Line 4 indented (with tab at beginning). + Line 5 indented. +This is example line 6. +""" diff --git a/test/fixtures/example/language.rb b/test/fixtures/example/language.rb new file mode 100644 index 00000000..99680c69 --- /dev/null +++ b/test/fixtures/example/language.rb @@ -0,0 +1,35 @@ +# Test for programming language: Ruby + +=begin +@api {get} /language/ruby Ruby +@apiName GetLanguageRuby +@apiGroup Language +@apiVersion 0.4.0 +@apiDescription Test for Ruby Comment-Syntax. +=end + +=begin + @api {get} /language/ruby/indented1 Ruby indented 1 + @apiName GetLanguageRubyIndented1 + @apiGroup Language + @apiVersion 0.4.0 + @apiExample Test for indented comment. + This is example line 2. + This is example line 3. + Line 4 indented (with tab at beginning). + Line 5 indented. + This is example line 6. +=end + +=begin +@api {get} /language/ruby/indented2 Ruby indented 2 +@apiName GetLanguageRubyIndented2 +@apiGroup Language +@apiVersion 0.4.0 +@apiExample Test for indented comment. +This is example line 2. +This is example line 3. + Line 4 indented (with tab at beginning). + Line 5 indented. +This is example line 6. +=end