Merge pull request #30 from wehrstedt/template-path

Template can't be used with grunt

Author: wehrstedt

.npmignore

@@ -2,13 +2,11 @@
 exampleProject/
 node_modules/
 src/
-src-out/core/publish-example.js
-src-out/test
-src-out/**/*.js.map
-src-out/**/*.d.ts
+src-out/
 typings/
 .editorconfig
 .travis.yml
 gruntfile.js
+publish-example.js
 tsconfig.json
 tslint.json

CHANGELOG.md

@@ -1,5 +1,10 @@
 ## Changelog
 
+# v0.8.8
+Bugfixes:
+ - You can now use the template with grunt or simply use the module path as for the template parameter for jsdoc (https://github.com/otris/jsdoc-tsd/issues/1)
+ - The description of an jsdoc item was not added if the @description-annotation was omitted
+
 # v0.8.7
 New features in this release:
  - New annotations: @callback, @template

package.json

@@ -1,14 +1,14 @@
 {
 	"name": "@otris/jsdoc-tsd",
-	"version": "0.8.7",
+	"version": "0.8.8",
 	"description": "JSDoc Template for generate typescript definition files from JSDoc comments",
 	"main": "src-out/core/publish.js",
 	"repository": {
 		"type": "git",
 		"url": "git+ssh://[email protected]:otris/jsdoc-tsd.git"
 	},
 	"scripts": {
-		"prepublish": "rm -rf src-out && tsc -p ./",
+		"prepublish": "rm -rf src-out && tsc -p ./ && cp src-out/core/*.js ./",
 		"compile": "tsc -watch -p ./",
 		"parse-example": "move /Y src-out\\core\\publish.js src-out\\core\\publish.backup.js && copy /Y src-out\\core\\publish-example.js src-out\\core\\publish.js && jsdoc -r exampleProject -t src-out\\core && move /Y src-out\\core\\publish.backup.js src-out\\core\\publish.js",
 		"test": "mocha --compilers=ts:ts-node/register --no-timeouts src/test/**/test.*.ts",

src/core/jsdoc-tsd-parser.ts

@@ -180,7 +180,7 @@ export class JSDocTsdParser {
 
 				if (addItem) {
 					if (addJsDocComment) {
-						parsedItem.jsDocComment = this.cleanJSDocComment(item.comment);
+						parsedItem.jsDocComment = this.cleanJSDocComment(item.comment, item.description);
 					}
 					this.handleFlags(item, parsedItem);
 					this.handleTags(item, parsedItem);
@@ -392,13 +392,19 @@ export class JSDocTsdParser {
 		return output;
 	}
 
-	private cleanJSDocComment(comment: string | undefined, addExample = false): string {
+	/**
+	 * Creates the comment for the jsdoc item
+	 * @param comment The complete comment text of the item
+	 * @param description The description (@description) of the item
+	 * @param addExample Indicates if examples should be omitted or not
+	 */
+	private cleanJSDocComment(comment: string | undefined, description:string = "", addExample = false): string {
 		let cleanLines = [];
 		let descriptionLines: string[] = [];
 		let exampleLines: string[] = [];
-		let description = false;
-		let example = false;
-		let classdesc = false;
+		let isDescription = false;
+		let isExample = false;
+		let isClassdesc = false;
 
 		if (comment) {
 			for (let line of comment.split(/\r?\n/)) {
@@ -414,24 +420,24 @@ export class JSDocTsdParser {
 				// tslint:disable-next-line:max-line-length
 				if (cleanedLine && (cleanedLine.startsWith("@param") || cleanedLine.startsWith("@throws") || cleanedLine.startsWith("@description") || cleanedLine.startsWith("@classdesc") || cleanedLine.startsWith("@example") || cleanedLine.startsWith("@return") || !cleanedLine.startsWith("@"))) {
 					if (cleanedLine.startsWith("@")) {
-						description = false;
-						example = false;
-						classdesc = false;
+						isDescription = false;
+						isExample = false;
+						isClassdesc = false;
 					}
-					if (cleanedLine.startsWith("@description")) {
+					if (cleanedLine.startsWith("@description") || cleanedLine === description) {
 						cleanedLine = cleanedLine.replace("@description ", "");
-						description = true;
+						isDescription = true;
 					} else if (cleanedLine.startsWith("@example")) {
-						example = true;
+						isExample = true;
 					} else if (cleanedLine.startsWith("@classdesc")) {
-						classdesc = true;
+						isClassdesc = true;
 					}
 
-					if (description) {
+					if (isDescription) {
 						descriptionLines.push(cleanedLine);
-					} else if (example) {
+					} else if (isExample) {
 						exampleLines.push(cleanedLine);
-					} else if (classdesc) {
+					} else if (isClassdesc) {
 						// the class-description is correctly added to the class already
 					} else if (/^@[^\s]+\s/.test(cleanedLine)) {
 						// add this line only if the annotation value is not empty
@@ -709,7 +715,7 @@ export class JSDocTsdParser {
 			constructorDeclaration = dom.create.constructor([]);
 		}
 
-		constructorDeclaration.jsDocComment = this.cleanJSDocComment(jsdocItem.comment);
+		constructorDeclaration.jsDocComment = this.cleanJSDocComment(jsdocItem.comment, jsdocItem.description);
 		domClass.members.push(constructorDeclaration);
 
 		return domClass;
@@ -724,7 +730,7 @@ export class JSDocTsdParser {
 		if (jsdocItem.properties) {
 			for (let property of jsdocItem.properties) {
 				let domEnumMember: dom.EnumMemberDeclaration = dom.create.enumValue(property.name, property.defaultvalue);
-				domEnumMember.jsDocComment = this.cleanJSDocComment(property.description);
+				domEnumMember.jsDocComment = this.cleanJSDocComment(property.comment, property.description);
 				domEnum.members.push(domEnumMember);
 			}
 		}
@@ -811,7 +817,7 @@ export class JSDocTsdParser {
 					}
 
 					let domProperty = dom.create.property(property.name, propertyType);
-					domProperty.jsDocComment = this.cleanJSDocComment(property.comment) || property.description; // normally the property 'comment' is for these types empty
+					domProperty.jsDocComment = this.cleanJSDocComment(property.description, property.description);
 					this.handleFlags(property, domProperty);
 
 					domInterface.members.push(domProperty);

src/test/class/test.parseClass.ts

@@ -41,7 +41,7 @@ describe("JSDocTsdParser.parse.class", () => {
 
 		expect(classDeclarations.members.length).to.eq(1);
 		let constr: dom.ConstructorDeclaration = classDeclarations.members[0] as dom.ConstructorDeclaration;
-		expect(constr.jsDocComment).to.eq("My Class\n@param myParam My param description");
+		expect(constr.jsDocComment).to.eq("@param myParam My param description");
 	});
 
 	it("should add an constructor with no params to the class members", () => {

src/test/description/test.parseDescription.ts

@@ -20,6 +20,6 @@ describe("JSDocTsdParser.cleanJSDocComment", () => {
 		// parsedClass.members[0] is constructor
 		let methodDeclaration: dom.MethodDeclaration = parsedClass.members[1] as dom.MethodDeclaration;
 		// description should be at the beginning
-		expect(methodDeclaration.jsDocComment).to.eq("My long description\nfirst line\nsecond line\nthird line\n@param myParamter My string parameter");
+		expect(methodDeclaration.jsDocComment).to.eq("My long description\nfirst line\nsecond line\nthird line\n@param myParamter My string parameter\n@returns My return value");
 	});
 });

src/test/function/test.jsdoc-tsd-parser.ts

@@ -407,6 +407,7 @@ describe("JSDocTsdParser.parse.function", () => {
 		 * @static
 		 * @function
 		 */`;
+		functionData.description = "A function";
 
 		parser = new JSDocTsdParser();
 		parser.parse([functionData]);
@@ -415,7 +416,7 @@ describe("JSDocTsdParser.parse.function", () => {
 
 		expect(functionDeclarations.length).to.equals(1);
 		let functionDeclaration = functionDeclarations[0];
-		functionDescription = `A function\n@param bla blub\n@throws {string} error`;
+		functionDescription = `A function\n@param bla blub\n@returns bla\n@throws {string} error`;
 		expect(functionDeclaration.jsDocComment).to.equals(functionDescription);
 	});
 
@@ -444,6 +445,7 @@ describe("JSDocTsdParser.parse.function", () => {
 		 * @static
 		 * @function
 		 */`;
+		functionData.description = "A function";
 
 		parser = new JSDocTsdParser();
 		parser.parse([functionData]);
@@ -452,7 +454,7 @@ describe("JSDocTsdParser.parse.function", () => {
 
 		expect(functionDeclarations.length).to.equals(1);
 		let functionDeclaration = functionDeclarations[0];
-		functionDescription = `A function\n@param bla blub\n@throws {string} error`;
+		functionDescription = `A function\n@param bla blub\n@returns bla\n@throws {string} error`;
 		expect(functionDeclaration.jsDocComment).to.equals(functionDescription);
 	});
 

src/test/interface/test.parseInterface.ts

@@ -33,7 +33,7 @@ describe("JSDocTsdParser.parse.interface", () => {
 		expect(parsedInterface.members.length).to.eq(2);
 
 		let methodDeclaration: dom.MethodDeclaration = parsedInterface.members[1] as dom.MethodDeclaration;
-		expect(methodDeclaration.jsDocComment).to.eq("A simple function\n@param myParamter My string parameter");
+		expect(methodDeclaration.jsDocComment).to.eq("A simple function\n@param myParamter My string parameter\n@returns My return value");
 	});
 
 	it("should create a number member of an interface", () => {

src/test/module/test.parseModule.ts

@@ -33,7 +33,7 @@ describe("JSDocTsdParser.parse.module", () => {
 		expect(parsedModule.members.length).to.eq(2);
 
 		let functionDeclaration: dom.FunctionDeclaration = parsedModule.members[1] as dom.FunctionDeclaration;
-		expect(functionDeclaration.jsDocComment).to.eq("my module function\n@param param1 first param\n@param param2 second param");
+		expect(functionDeclaration.jsDocComment).to.eq("my module function\n@param param1 first param\n@param param2 second param\n@returns function return value");
 	});
 
 	it("should create a number member of an module", () => {

src/test/test.since.ts

@@ -150,7 +150,7 @@ describe("Test for parsing the since tag", () => {
 		expect(results).haveOwnPropertyDescriptor("MyTestClass");
 	});
 
-	it("should not add the class definition if the tag is not a valid semver tag and no custom comparator is set", () => {
+	it("should add the class definition if the tag is not a valid semver tag and no custom comparator is set", () => {
 		let myClass: TDoclet = JSON.parse(JSON.stringify(emptyClassData));
 		myClass.since = "abc";
 		myClass.name = myClass.longname = "MyTestClass";
@@ -159,7 +159,7 @@ describe("Test for parsing the since tag", () => {
 		parser.parse([myClass]);
 
 		let results = parser.getResultItems();
-		expect(Object.keys(results).length).to.eq(0);
+		expect(Object.keys(results).length).to.eq(1);
 	});
 
 	it("should use the comparator function if it's passed as function", () => {