Bugfix: Allow usage of structures and titles in the same block.

wayt · Nov 30, 2013 · 907c4f2 · 907c4f2
1 parent e7e07af
commit 907c4f2
Show file tree

Hide file tree

Showing 9 changed files with 174 additions and 18 deletions.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -1,5 +1,11 @@
 # apiDoc Changelog
 
+#### 0.2.7
+Bugfix: Allow usage of structures and titles in the same block (https://github.com/apidoc/apidoc/issues/21)
+
+#### 0.2.6
+Give some indication, in case file listing with fails (Johannes Zellner https://github.com/apidoc/apidoc/pull/20)
+
 #### 0.2.5
 Allow multiple structure includes.
 Split and extend test-files.

diff --git a/lib/parser.js b/lib/parser.js
@@ -105,6 +105,7 @@ Parser.prototype._parseBlockElements = function(indexApiBlocks, detectedElements
 			local: {}
 		};
 		var preventGlobal = false;
+		var countAllowedMultiple = 0;
 		for(var j = 0; j < elements.length; j += 1)
 		{
 			var element = elements[j];
@@ -129,10 +130,13 @@ Parser.prototype._parseBlockElements = function(indexApiBlocks, detectedElements
 					);
 				}
 
+				// Check if it is allowed to add to global namespace.
 				if(self.parsers[element.name].preventGlobal && self.parsers[element.name].preventGlobal === true)
 				{
 					preventGlobal = true;
-					if(Object.keys(blockData.global).length > 0)
+					// Check if count global namespace entries > count allowed
+					// (e.g. @successTitle is global, but should co-exist with @apiErrorStructure)
+					if(Object.keys(blockData.global).length > countAllowedMultiple)
 					{
 						throw new Error("Can't set \"@" + element.sourceName + "\" in file \"" + self.filename +
 							"\" block number " + (blockIndex + 1) + ", only one definition or use is allowed in the same block."
@@ -149,7 +153,11 @@ Parser.prototype._parseBlockElements = function(indexApiBlocks, detectedElements
 					{
 						var allowMultiple = self.parsers[element.name].allowMultiple || false;
 
-						if( ! allowMultiple)
+						if(allowMultiple)
+						{
+							countAllowedMultiple += 1;
+						}
+						else
 						{
 							if(Object.keys(blockData.global).length > 0)
 							{

diff --git a/lib/plugins/worker_structure.js b/lib/plugins/worker_structure.js
@@ -65,7 +65,7 @@ function postProcess(parsedFiles, filenames, preProcessResults, structureName, d
 			var block = parsedFile[blockIndex];
 			if(block["local"][structureName])
 			{
-				for(var structureIndex = 0; structureIndex < block["local"][structureName].length; structureIndex++)
+				for(var structureIndex = 0; structureIndex < block["local"][structureName].length; structureIndex += 1)
 				{
 					var name = block["local"][structureName][structureIndex];
 					var version = "0.0.0";

diff --git a/package.json b/package.json
@@ -1,6 +1,6 @@
 {
   "name": "apidoc",
-  "version": "0.2.6",
+  "version": "0.2.7",
   "description": "RESTful web API Documentation Generator",
   "author": "Peter Rottmann <[email protected]>",
   "license": "MIT",

diff --git a/test/fixtures/api_data.js b/test/fixtures/api_data.js
@@ -33,6 +33,46 @@ define({ api: [
     },
     "filename": "test\\fixtures\\example\\error_structure.js"
   },
+  {
+    "type": "post",
+    "url": "/test/title_and_error",
+    "title": "Title and Structure",
+    "name": "PostTitleAndError",
+    "group": "Error",
+    "version": "0.1.0",
+    "description": "Use of Title and Structures in the same block.",
+    "success": {
+      "fields": {
+        "204 No Content. Added to global namespace.": [
+          {
+            "group": "204",
+            "field": "message",
+            "optional": false,
+            "description": "Successfully deleted."
+          }
+        ]
+      }
+    },
+    "error": {
+      "fields": {
+        "Error 4xx": [
+          {
+            "group": "Error 4xx",
+            "field": "error3Error",
+            "optional": false,
+            "description": "This is Error 3 (local)."
+          },
+          {
+            "group": "Error 4xx",
+            "field": "error1Error",
+            "optional": false,
+            "description": "This is Error 1."
+          }
+        ]
+      }
+    },
+    "filename": "test\\fixtures\\example\\title_and_structure.js"
+  },
   {
     "type": "get",
     "url": "/test/:id",
@@ -509,9 +549,9 @@ define({ api: [
         "Parameter": [
           {
             "group": "Parameter",
-            "field": "field1",
+            "field": "field2",
             "optional": false,
-            "description": "This is Field 1."
+            "description": "This is Field 2."
           }
         ]
       }
@@ -528,9 +568,9 @@ define({ api: [
         "Parameter": [
           {
             "group": "Parameter",
-            "field": "field2",
+            "field": "field1",
             "optional": false,
-            "description": "This is Field 2."
+            "description": "This is Field 1."
           }
         ]
       }
@@ -578,5 +618,24 @@ define({ api: [
     "url": "",
     "version": "0.0.0",
     "filename": "test\\fixtures\\example\\success_structure.js"
+  },
+  {
+    "error": {
+      "fields": {
+        "Error 4xx": [
+          {
+            "group": "Error 4xx",
+            "field": "error1Error",
+            "optional": false,
+            "description": "This is Error 1."
+          }
+        ]
+      }
+    },
+    "group": "title_and_structure.js",
+    "type": "",
+    "url": "",
+    "version": "0.0.0",
+    "filename": "test\\fixtures\\example\\title_and_structure.js"
   }
 ] });
diff --git a/test/fixtures/api_data.json b/test/fixtures/api_data.json
@@ -33,6 +33,46 @@
     },
     "filename": "test\\fixtures\\example\\error_structure.js"
   },
+  {
+    "type": "post",
+    "url": "/test/title_and_error",
+    "title": "Title and Structure",
+    "name": "PostTitleAndError",
+    "group": "Error",
+    "version": "0.1.0",
+    "description": "Use of Title and Structures in the same block.",
+    "success": {
+      "fields": {
+        "204 No Content. Added to global namespace.": [
+          {
+            "group": "204",
+            "field": "message",
+            "optional": false,
+            "description": "Successfully deleted."
+          }
+        ]
+      }
+    },
+    "error": {
+      "fields": {
+        "Error 4xx": [
+          {
+            "group": "Error 4xx",
+            "field": "error3Error",
+            "optional": false,
+            "description": "This is Error 3 (local)."
+          },
+          {
+            "group": "Error 4xx",
+            "field": "error1Error",
+            "optional": false,
+            "description": "This is Error 1."
+          }
+        ]
+      }
+    },
+    "filename": "test\\fixtures\\example\\title_and_structure.js"
+  },
   {
     "type": "get",
     "url": "/test/:id",
@@ -509,9 +549,9 @@
         "Parameter": [
           {
             "group": "Parameter",
-            "field": "field1",
+            "field": "field2",
             "optional": false,
-            "description": "This is Field 1."
+            "description": "This is Field 2."
           }
         ]
       }
@@ -528,9 +568,9 @@
         "Parameter": [
           {
             "group": "Parameter",
-            "field": "field2",
+            "field": "field1",
             "optional": false,
-            "description": "This is Field 2."
+            "description": "This is Field 1."
           }
         ]
       }
@@ -578,5 +618,24 @@
     "url": "",
     "version": "0.0.0",
     "filename": "test\\fixtures\\example\\success_structure.js"
+  },
+  {
+    "error": {
+      "fields": {
+        "Error 4xx": [
+          {
+            "group": "Error 4xx",
+            "field": "error1Error",
+            "optional": false,
+            "description": "This is Error 1."
+          }
+        ]
+      }
+    },
+    "group": "title_and_structure.js",
+    "type": "",
+    "url": "",
+    "version": "0.0.0",
+    "filename": "test\\fixtures\\example\\title_and_structure.js"
   }
 ]
diff --git a/test/fixtures/api_project.js b/test/fixtures/api_project.js
@@ -1,10 +1,10 @@
 define({
   "name": "apidoc",
-  "version": "0.2.4",
+  "version": "0.2.7",
   "description": "RESTful web API Documentation Generator",
   "apidoc": "",
   "generator": {
-    "version": "0.2.4",
-    "time": "2013-09-21T15:08:45.041Z"
+    "version": "0.2.7",
+    "time": "2013-11-30T10:04:13.365Z"
   }
 });
diff --git a/test/fixtures/api_project.json b/test/fixtures/api_project.json
@@ -1,10 +1,10 @@
 {
   "name": "apidoc",
-  "version": "0.2.4",
+  "version": "0.2.7",
   "description": "RESTful web API Documentation Generator",
   "apidoc": "",
   "generator": {
-    "version": "0.2.4",
-    "time": "2013-09-21T15:08:45.041Z"
+    "version": "0.2.7",
+    "time": "2013-11-30T10:04:13.365Z"
   }
 }
diff --git a/test/fixtures/example/title_and_structure.js b/test/fixtures/example/title_and_structure.js
@@ -0,0 +1,24 @@
+/**
+ * Use of Title and Structures in the same block.
+ */
+
+/**
+ * @apiDefineErrorStructure TitleAndError1
+ *
+ * @apiError error1Error This is Error 1.
+ */
+
+/**
+ * @api {post} /test/title_and_error Title and Structure
+ * @apiName PostTitleAndError
+ * @apiGroup Error
+ * @apiVersion 0.1.0
+ * @apiDescription Use of Title and Structures in the same block.
+ *
+ * @apiSuccessTitle (204) 204 No Content. Added to global namespace.
+ * @apiSuccess (204) message Successfully deleted.
+ *
+ * @apiErrorStructure TitleAndError1
+ *
+ * @apiError error3Error This is Error 3 (local).
+ */