From c5716400fce681e9afc31e852f7f11e608fb735a Mon Sep 17 00:00:00 2001 From: web-padawan Date: Wed, 15 Jul 2020 16:14:23 +0300 Subject: [PATCH] Preserve attribute tags in JSDoc comments --- .../gen-typescript-declarations/src/gen-ts.ts | 3 ++ .../paper-button-behavior.d.ts | 1 + .../paper-button-behavior.d.ts | 1 + .../paper-button-behavior.d.ts | 1 + .../paper-button-behavior.d.ts | 1 + .../src/test/serialize_test.ts | 31 +++++++++++++++++++ .../src/ts-ast/declarations.ts | 11 ++++++- 7 files changed, 48 insertions(+), 1 deletion(-) diff --git a/packages/gen-typescript-declarations/src/gen-ts.ts b/packages/gen-typescript-declarations/src/gen-ts.ts index 2694273e6..920348d83 100644 --- a/packages/gen-typescript-declarations/src/gen-ts.ts +++ b/packages/gen-typescript-declarations/src/gen-ts.ts @@ -836,6 +836,9 @@ class TypeGenerator { readOnly: property.readOnly, }); p.description = property.description || ''; + if (property.jsdoc) { + p.tags = property.jsdoc.tags || []; + } tsProperties.push(p); } return tsProperties; diff --git a/packages/gen-typescript-declarations/src/test/goldens/paper-behaviors-2/paper-button-behavior.d.ts b/packages/gen-typescript-declarations/src/test/goldens/paper-behaviors-2/paper-button-behavior.d.ts index 1baa77bfe..28a4afd56 100644 --- a/packages/gen-typescript-declarations/src/test/goldens/paper-behaviors-2/paper-button-behavior.d.ts +++ b/packages/gen-typescript-declarations/src/test/goldens/paper-behaviors-2/paper-button-behavior.d.ts @@ -24,6 +24,7 @@ declare namespace Polymer { * The z-depth of this element, from 0-5. Setting to 0 will remove the * shadow, and each increasing number greater than 0 will be "deeper" * than the last. + * @attribute elevation */ readonly elevation: number|null|undefined; hostAttributes: object|null; diff --git a/packages/gen-typescript-declarations/src/test/goldens/paper-behaviors-3/paper-button-behavior.d.ts b/packages/gen-typescript-declarations/src/test/goldens/paper-behaviors-3/paper-button-behavior.d.ts index 8cdae00e6..591f7c714 100644 --- a/packages/gen-typescript-declarations/src/test/goldens/paper-behaviors-3/paper-button-behavior.d.ts +++ b/packages/gen-typescript-declarations/src/test/goldens/paper-behaviors-3/paper-button-behavior.d.ts @@ -24,6 +24,7 @@ interface PaperButtonBehavior extends IronButtonState, IronControlState, PaperRi * The z-depth of this element, from 0-5. Setting to 0 will remove the * shadow, and each increasing number greater than 0 will be "deeper" * than the last. + * @attribute elevation */ readonly elevation: number|null|undefined; hostAttributes: object|null; diff --git a/packages/gen-typescript-declarations/src/test/goldens_goog/paper-behaviors-2/paper-button-behavior.d.ts b/packages/gen-typescript-declarations/src/test/goldens_goog/paper-behaviors-2/paper-button-behavior.d.ts index 1baa77bfe..28a4afd56 100644 --- a/packages/gen-typescript-declarations/src/test/goldens_goog/paper-behaviors-2/paper-button-behavior.d.ts +++ b/packages/gen-typescript-declarations/src/test/goldens_goog/paper-behaviors-2/paper-button-behavior.d.ts @@ -24,6 +24,7 @@ declare namespace Polymer { * The z-depth of this element, from 0-5. Setting to 0 will remove the * shadow, and each increasing number greater than 0 will be "deeper" * than the last. + * @attribute elevation */ readonly elevation: number|null|undefined; hostAttributes: object|null; diff --git a/packages/gen-typescript-declarations/src/test/goldens_goog/paper-behaviors-3/paper-button-behavior.d.ts b/packages/gen-typescript-declarations/src/test/goldens_goog/paper-behaviors-3/paper-button-behavior.d.ts index 69a31c369..c0b71b135 100644 --- a/packages/gen-typescript-declarations/src/test/goldens_goog/paper-behaviors-3/paper-button-behavior.d.ts +++ b/packages/gen-typescript-declarations/src/test/goldens_goog/paper-behaviors-3/paper-button-behavior.d.ts @@ -26,6 +26,7 @@ declare module 'goog:polymer.paperBehaviors.paperButtonBehavior' { * The z-depth of this element, from 0-5. Setting to 0 will remove the * shadow, and each increasing number greater than 0 will be "deeper" * than the last. + * @attribute elevation */ readonly elevation: number|null|undefined; hostAttributes: object|null; diff --git a/packages/gen-typescript-declarations/src/test/serialize_test.ts b/packages/gen-typescript-declarations/src/test/serialize_test.ts index d75dff51a..46f926f72 100644 --- a/packages/gen-typescript-declarations/src/test/serialize_test.ts +++ b/packages/gen-typescript-declarations/src/test/serialize_test.ts @@ -19,6 +19,37 @@ suite('serializeTsDeclarations', () => { assert.equal(p.serialize(), '"my-unsafe-property": string;\n'); }); + test('property with custom tag', () => { + const p = new ts.Property({ + name: 'myProperty', + tags: [{ title: 'attr', description: '{string} my-property' }], + type: new ts.NameType('string'), + }); + assert.equal(p.serialize(), ` +/** + * @attr {string} my-property + */ +myProperty: string; +`); + }); + + test('property with description and custom tag', () => { + const p = new ts.Property({ + name: 'myProperty', + tags: [{ title: 'attr', description: '{string} my-property' }], + type: new ts.NameType('string'), + }); + p.description = 'This is my property.\nIt has a multi-line description.'; + assert.equal(p.serialize(), ` +/** + * This is my property. + * It has a multi-line description. + * @attr {string} my-property + */ +myProperty: string; +`); + }); + test('function with description', () => { const m = new ts.Function({ name: 'MyMethod', diff --git a/packages/gen-typescript-declarations/src/ts-ast/declarations.ts b/packages/gen-typescript-declarations/src/ts-ast/declarations.ts index 7e501aa4e..d6988a3cd 100644 --- a/packages/gen-typescript-declarations/src/ts-ast/declarations.ts +++ b/packages/gen-typescript-declarations/src/ts-ast/declarations.ts @@ -9,6 +9,7 @@ * rights grant found at http://polymer.github.io/PATENTS.txt */ +import {Tag} from 'doctrine'; import {formatComment, indent, quotePropertyName} from './formatting'; import {Node} from './index'; import {anyType, ParamType, Type} from './types'; @@ -358,17 +359,20 @@ export class Property { description: string; type: Type; readOnly: boolean; + tags: Tag[] = []; constructor(data: { name: string, description?: string, type?: Type, readOnly?: boolean, + tags?: Tag[], }) { this.name = data.name; this.description = data.description || ''; this.type = data.type || anyType; this.readOnly = data.readOnly || false; + this.tags = data.tags || []; } * traverse(): Iterable { @@ -379,8 +383,13 @@ export class Property { serialize(depth: number = 0): string { let out = ''; const i = indent(depth); + const tags = this.tags + .filter((tag) => tag.title === 'attr' || tag.title === 'attribute') + .map((tag) => '@' + tag.title + ' ' + tag.description).join('\n'); if (this.description) { - out += '\n' + formatComment(this.description, depth); + out += '\n' + formatComment(tags ? this.description + '\n' + tags : this.description, depth); + } else if (tags) { + out += '\n' + formatComment(tags, depth); } out += i; if (this.readOnly) {