Add mergeDuplicateParams option

src/config/entities/ParsingConfig.ts

@@ -0,0 +1,14 @@
+import IParsingConfig from "../interfaces/IParsingConfig";
+
+export default class ParsingConfig implements IParsingConfig {
+	/**
+	 * Warn about unrecognized JSDoc tags
+	 */
+	public warnUnrecognizedTags: boolean = true;
+
+	/**
+	 * If true, the arguments with the same name will be merged.
+	 * If false, it will be added as different arguments.
+	 */
+	public mergeDuplicateParams: boolean = false;
+}

src/config/entities/ProjectConfig.ts

@@ -1,7 +1,9 @@
 import IOutputConfig from "../interfaces/IOutputConfig";
+import IParsingConfig from "../interfaces/IParsingConfig";
 import IProjectConfig from "../interfaces/IProjectConfig";
 import IScriptValidationRule from "../interfaces/IScriptValidationRules";
 import OutputConfig from "./OutputConfig";
+import ParsingConfig from "./ParsingConfig";
 import ScriptValidationRules from "./ScriptValidationRules";
 
 /**
@@ -25,9 +27,9 @@ export default class ProjectConfig implements IProjectConfig {
 	public root: string = "scripts";
 
 	/**
-	 * Warn about unrecognized JSDoc tags
+	 * The parser configuration
 	 */
-	public warnUnrecognizedTags: boolean = true;
+	public parser: IParsingConfig = new ParsingConfig();
 
 	/**
 	 * Rules for validating scripts

src/config/interfaces/IParsingConfig.d.ts

@@ -0,0 +1,4 @@
+export default interface IParsingConfig {
+	warnUnrecognizedTags: boolean;
+	mergeDuplicateParams: boolean;
+}

src/config/interfaces/IProjectConfig.d.ts

@@ -1,11 +1,12 @@
 import IOutputConfig from "./IOutputConfig";
 import IScriptValidationRules from "./IScriptValidationRules";
+import IParsingConfig from "./IParsingConfig";
 
 
 export default interface IProjectConfig {
 	output: IOutputConfig;
-	warnUnrecognizedTags: boolean;
 	pattern: string;
 	root: string;
+	parser: IParsingConfig;
 	scripts: IScriptValidationRules;
 }

src/generator/DocumentationExtractor.ts

@@ -1,6 +1,7 @@
 import { inject, injectable } from "inversify";
 import { TYPES } from "../types";
 
+import IParsingConfig from "../config/interfaces/IParsingConfig";
 import IScriptValidationRules from "../config/interfaces/IScriptValidationRules";
 import DocScript from "../doc_models/DocScript";
 import GMSubscript from "../gm_project/GMSubscript";
@@ -36,13 +37,11 @@ export default class DocumentationExtractor implements IDocumentationExtractor {
 	public extractDocScripts(
 		subscriptsIterator: IterableIterator<GMSubscript>,
 		rules: IScriptValidationRules,
-		warnUnrecognizedTags: boolean,
+		parsingConfig: IParsingConfig,
 	): DocScript[] {
 		const arr = [];
-
-		this._jsDocParser.warnUnrecognizedTags = warnUnrecognizedTags;
 		for (const subScript of subscriptsIterator) {
-			const docScript = this._jsDocParser.parse(subScript.name, subScript.text);
+			const docScript = this._jsDocParser.parse(subScript.name, subScript.text, parsingConfig);
 			const validable = new ValidableScript(docScript, subScript.text);
 			if (this._scriptValidator.validate(validable, rules)) {
 				arr.push(docScript);

src/generator/ScriptLoader.ts

@@ -40,6 +40,6 @@ export default class ScriptLoader implements IScriptLoader {
 			throw new Error(`Error loading file ${pathStr}`);
 		}
 		const it = gmScript.subScripts(str);
-		return this._extractor.extractDocScripts(it, config.scripts, config.warnUnrecognizedTags);
+		return this._extractor.extractDocScripts(it, config.scripts, config.parser);
 	}
 }

src/generator/interfaces/IDocumentationExtractor.d.ts

@@ -3,7 +3,8 @@ import IProjectConfig from "../../config/interfaces/IProjectConfig";
 import IScriptValidationRules from "../../config/interfaces/IScriptValidationRules";
 import IGMScript from "../../gm_project/interfaces/IGMScript";
 import GMSubscript from "../../gm_project/GMSubscript";
+import IParsingConfig from "../../config/interfaces/IParsingConfig";
 
 export default interface IDocumentationExtractor {
-	extractDocScripts(subscriptsIterator: IterableIterator<GMSubscript>, rules: IScriptValidationRules, warnUnrecognizedTags: boolean): DocScript[];
+	extractDocScripts(subscriptsIterator: IterableIterator<GMSubscript>, rules: IScriptValidationRules, parsingConfig: IParsingConfig): DocScript[];
 }

src/parser/DocScriptFactory.ts

@@ -10,16 +10,25 @@ import StringUtils from "./StringUtils";
  */
 export default class DocScriptFactory {
 
+	/**
+	 * If true, the arguments with the same name will be merged.
+	 * If false, it will be added as different arguments.
+	 */
+	private _mergeDuplicateParams: boolean;
+
 	/**
 	 * The DocScript to generate
 	 */
 	private _script: DocScript;
 
+	private _paramsMap: Map<string, DocParam> = new Map();
+
 	/**
 	 * Creates a DocScriptFactory to build DocScript objects.
 	 */
-	public constructor(name: string) {
+	public constructor(name: string, mergeDuplicateParams: boolean = false) {
 		this._script = new DocScript(name);
+		this._mergeDuplicateParams = mergeDuplicateParams;
 	}
 
 	/**
@@ -63,7 +72,20 @@ export default class DocScriptFactory {
 		str = StringUtils.compactHtmlSingleParagraph(str);
 		param.description = str;
 
-		this._script.params.push(param);
+		const originalParam = this._paramsMap.get(param.name);
+		if (originalParam) {
+			if (this._mergeDuplicateParams) {
+				originalParam.description += " " + param.description;
+				originalParam.optional = param.optional;
+				originalParam.type = param.type;
+			} else {
+				this._script.params.push(param);
+			}
+		} else {
+			this._paramsMap.set(param.name, param);
+			this._script.params.push(param);
+		}
+
 		this._script.undocumented = false;
 	}
 

src/parser/JSDocParser.ts

@@ -1,5 +1,7 @@
 import parse = require("comment-parser");
 import { inject, injectable } from "inversify";
+import ParsingConfig from "../config/entities/ParsingConfig";
+import IParsingConfig from "../config/interfaces/IParsingConfig";
 import DocScript from "../doc_models/DocScript";
 import IReporter from "../reporter/interfaces/IReporter";
 import { TYPES } from "../types";
@@ -12,11 +14,6 @@ import IJSDocParser from "./interfaces/IJSDocParser";
 @injectable()
 export default class JSDocParser implements IJSDocParser {
 
-	/**
-	 * Should warn about unrecognized JSDoc tags?
-	 */
-	public warnUnrecognizedTags: boolean = true;
-
 	/**
 	 * The reporter to use
 	 */
@@ -30,18 +27,20 @@ export default class JSDocParser implements IJSDocParser {
 	 * @param text The script content
 	 * @returns A new DocScript object
 	 */
-	public parse(name: string, text: string): DocScript {
+	public parse(name: string, text: string, parsingConfig?: IParsingConfig): DocScript {
+
+		parsingConfig = parsingConfig || new ParsingConfig();
 
 		const comments = parse(text);
 
-		const factory = new DocScriptFactory(name);
+		const factory = new DocScriptFactory(name, parsingConfig.mergeDuplicateParams);
 
 		for (const comment of comments) {
 			if (comment.description) {
 				factory.setDescription(comment.description);
 			}
 			for (const tag of comment.tags) {
-				this._parseTag(factory, tag, name);
+				this._parseTag(factory, tag, name, parsingConfig.warnUnrecognizedTags);
 			}
 		}
 
@@ -54,7 +53,7 @@ export default class JSDocParser implements IJSDocParser {
 	 * @param tag The tag to add
 	 * @param name The name of the script to add the tag to
 	 */
-	private _parseTag(factory: DocScriptFactory, tag: CommentParser.Tag, name: string) {
+	private _parseTag(factory: DocScriptFactory, tag: CommentParser.Tag, name: string, warnUnrecognizedTags: boolean) {
 		switch (tag.tag.toLowerCase()) {
 			case "param":
 			case "arg":
@@ -82,7 +81,7 @@ export default class JSDocParser implements IJSDocParser {
 				factory.setFunction(this._parseFunction(this._reconstructTag(tag)));
 				break;
 			default:
-				if (this.warnUnrecognizedTags) {
+				if (warnUnrecognizedTags) {
 					this._reporter.warn(`Unrecognized tag "${ tag.tag.toLowerCase() }" at script "${ name }"`);
 				}
 		}

src/parser/interfaces/IJSDocParser.d.ts

@@ -1,7 +1,7 @@
 import DocScript from "../../doc_models/DocScript";
 import IReporter from "../../reporter/interfaces/IReporter";
+import IParsingConfig from "../../config/interfaces/IParsingConfig";
 
 export default interface IJSDocParser {
-	warnUnrecognizedTags: boolean;
-	parse(name: string, text: string): DocScript;
+	parse(name: string, text: string, parsingConfig?: IParsingConfig): DocScript;
 }

tests/unit/__mock__/MockDocumentationExtractor.mock.ts

@@ -1,4 +1,5 @@
 import { injectable } from "inversify";
+import IParsingConfig from "../../../src/config/interfaces/IParsingConfig";
 import IScriptValidationRules from "../../../src/config/interfaces/IScriptValidationRules";
 import DocScript from "../../../src/doc_models/DocScript";
 import IDocumentationExtractor from "../../../src/generator/interfaces/IDocumentationExtractor";
@@ -8,11 +9,10 @@ import GMSubscript from "../../../src/gm_project/GMSubscript";
 
 @injectable()
 export default class MockDocumentationExtractor implements IDocumentationExtractor {
-	public warnUnrecognizedTags: boolean;
 	public extractDocScripts(
 		_subscriptsIterator: IterableIterator<GMSubscript>,
 		_rules: IScriptValidationRules,
-		_warnUnrecognizedTags: boolean,
+		_parsingConfig: IParsingConfig,
 	): DocScript[] {
 		throw new Error("Method not implemented.");
 	}

tests/unit/generator/DocumentationExtractor.spec.ts

@@ -8,6 +8,7 @@ import {
 import { Container, injectable } from "inversify";
 import { TYPES } from "../../../src/types";
 
+import ParsingConfig from "../../../src/config/entities/ParsingConfig";
 import ScriptValidationRules from "../../../src/config/entities/ScriptValidationRules";
 import IScriptValidationRules from "../../../src/config/interfaces/IScriptValidationRules";
 import DocScript from "../../../src/doc_models/DocScript";
@@ -21,7 +22,6 @@ import IValidableScript from "../../../src/validation/interfaces/IValidableScrip
 
 @injectable()
 class MockJSDocParser implements IJSDocParser {
-	public warnUnrecognizedTags: boolean = false;
 	public parse(name: string, _text: string): DocScript {
 		return new DocScript(name);
 	}
@@ -51,9 +51,8 @@ export class DocumentationExtractorFixture {
 		const extractor = container.resolve(DocumentationExtractor);
 
 		const it = this._mockIteratorFunction();
-		const docs = extractor.extractDocScripts(it, new ScriptValidationRules(), true);
+		const docs = extractor.extractDocScripts(it, new ScriptValidationRules(), new ParsingConfig());
 
-		Expect(jsDocParser.warnUnrecognizedTags).toBe(true);
 		Expect(docs.length).toBe(2);
 		Expect(docs[0].name).toBe("bar"); // scripts are sorted alphabetically
 		Expect(docs[1].name).toBe("foo");

tests/unit/generator/ScriptLoader.spec.ts

@@ -40,7 +40,6 @@ class MockDocumentationExtractor implements IDocumentationExtractor {
 	public extractDocScripts(
 		_subscriptsIterator: IterableIterator<GMSubscript>,
 		_rules: IScriptValidationRules,
-		_warnUnrecognizedTags: boolean,
 	): DocScript[] {
 		return [new DocScript("hi")];
 	}

tests/unit/parser/DocScriptFactory.spec.ts

@@ -95,4 +95,40 @@ export class DocScriptFactoryFixture {
 		Expect((script.returns as DocReturns).type).toBe("return_type");
 		Expect((script.returns as DocReturns).description).toBe("return_description");
 	}
+
+	@Test("Should merge duplicated params")
+	public mergeDuplicatedParams() {
+		this.factory = new DocScriptFactory("name", true);
+		this.factory.addParam("foo", "foo_type", false, "description1");
+		this.factory.addParam("foo", "foo2_type", true, "description2");
+		this.factory.addParam("foo", "foo3_type", true, "description3");
+		this.factory.addParam("bar", "", true, "param2_description");
+
+		const script = this.factory.make();
+		const params = script.params;
+		Expect(params.length).toBe(2);
+
+		Expect(params[0].name).toBe("foo");
+		Expect(params[0].type).toBe("foo3_type");
+		Expect(params[0].optional).toBe(true);
+		Expect(params[0].description).toBe("description1 description2 description3");
+
+		Expect(params[1].name).toBe("bar");
+		Expect(params[1].type).toBe("");
+		Expect(params[1].optional).toBe(true);
+		Expect(params[1].description).toBe("param2_description");
+	}
+
+	@Test("Should NOT merge duplicated params")
+	public shouldNOTmergeDuplicatedParams() {
+		this.factory = new DocScriptFactory("name", false);
+		this.factory.addParam("foo", "foo_type", false, "description1");
+		this.factory.addParam("foo", "foo2_type", true, "description2");
+		this.factory.addParam("foo", "foo3_type", true, "description3");
+		this.factory.addParam("bar", "", true, "param2_description");
+
+		const script = this.factory.make();
+		const params = script.params;
+		Expect(params.length).toBe(4);
+	}
 }