[labs/analyzer] Support const function/class declarations by kevinpschaaf · Pull Request #3662 · lit/lit

kevinpschaaf · 2023-02-11T01:16:15Z

Adds support for analyzing const variables initialized to class or function expressions as ClassDeclaration and FunctionDeclaration, respectively:

// Class declaration:
class Class1 { ... }
// Const variable initialized to a class expression (now also analyzed as a ClassDeclaration):
const Class2 = class { ... };

// Function declaration:
function fn1() { ... }
// Const variable initialized to a function expression (now also analyzed as a FunctionDeclaration):
const fn2 = function() { ... };
const fn3 = () => { ... }

Since we didn't previously have a classes test suite itself (the class analysis was mostly covered by a combination of the LitElement basic and jsdoc tests) and I needed to add some more clasess tests, I pulled the class-specific tests out of lit-element/jsdoc_test. and vanilla-element/jsdoc_test.js and moved them to a new javascript/classes_tests.js, and added the new const tests there. Now, the jsdoc test just contains CE-specific information that's only pulled out of jsdoc (e.g. slot, custom props, etc.). I think this makes the test organization more logical.

changeset-bot · 2023-02-11T01:16:18Z

🦋 Changeset detected

Latest commit: c2f29ed

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 7 packages

Name	Type
@lit-labs/analyzer	Minor
@lit-labs/cli	Patch
@lit-labs/gen-manifest	Patch
@lit-labs/gen-utils	Patch
@lit-labs/gen-wrapper-angular	Patch
@lit-labs/gen-wrapper-react	Patch
@lit-labs/gen-wrapper-vue	Patch

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

github-actions · 2023-02-11T01:16:42Z

📊 Tachometer Benchmark Results

Summary

nop-update

lit-html-kitchen-sink: unsure 🔍 -4% - +8% (-0.59ms - +1.36ms)
^{this-change vs tip-of-tree}

render

lit-element-list: 80.83ms - 85.36ms
lit-html-kitchen-sink: unsure 🔍 -7% - +7% (-2.27ms - +2.41ms)
^{this-change vs tip-of-tree}
lit-html-repeat: unsure 🔍 -5% - +5% (-0.62ms - +0.56ms)
^{this-change vs tip-of-tree}
lit-html-template-heavy: unsure 🔍 -2% - +4% (-0.89ms - +1.89ms)
^{this-change vs tip-of-tree}
reactive-element-list: unsure 🔍 -4% - +2% (-2.07ms - +0.87ms)
^{this-change vs tip-of-tree}

update

lit-element-list: 677.95ms - 686.88ms
lit-html-kitchen-sink: unsure 🔍 -4% - +4% (-3.28ms - +3.06ms)
^{this-change vs tip-of-tree}
lit-html-repeat: unsure 🔍 -3% - +2% (-9.16ms - +4.29ms)
^{this-change vs tip-of-tree}
lit-html-template-heavy: unsure 🔍 -0% - +1% (-0.42ms - +1.24ms)
^{this-change vs tip-of-tree}
reactive-element-list: unsure 🔍 -0% - +1% (-2.98ms - +4.72ms)
^{this-change vs tip-of-tree}

update-reflect

lit-element-list: 681.60ms - 689.04ms
reactive-element-list: unsure 🔍 -1% - +0% (-4.48ms - +2.87ms)
^{this-change vs tip-of-tree}

Results

lit-element-list

Browser: chrome-headless 110.0.5481.177
Sample size: 50
Built by: Benchmarks #4481
Commit: 03db693

render

Version	Avg time	vs
	80.83ms - 85.36ms	-

update

Version	Avg time	vs
	677.95ms - 686.88ms	-

update-reflect

Version	Avg time	vs
	681.60ms - 689.04ms	-

lit-html-kitchen-sink

Browser: chrome-headless 110.0.5481.177
Sample size: 30
Built by: Benchmarks #4481
Commit: 03db693

render

Version	Avg time	vs this-change	vs tip-of-tree tip-of-tree	vs previous-release previous-release
this-change	32.03ms - 35.48ms	-	unsure 🔍 -7% - +7% -2.27ms - +2.41ms	unsure 🔍 -6% - +8% -1.92ms - +2.81ms
tip-of-tree tip-of-tree	32.10ms - 35.27ms	unsure 🔍 -7% - +7% -2.41ms - +2.27ms	-	unsure 🔍 -6% - +8% -1.89ms - +2.64ms
previous-release previous-release	31.69ms - 34.93ms	unsure 🔍 -8% - +6% -2.81ms - +1.92ms	unsure 🔍 -8% - +6% -2.64ms - +1.89ms	-

update

Version	Avg time	vs this-change	vs tip-of-tree tip-of-tree	vs previous-release previous-release
this-change	75.71ms - 80.24ms	-	unsure 🔍 -4% - +4% -3.28ms - +3.06ms	unsure 🔍 -3% - +4% -2.17ms - +3.47ms
tip-of-tree tip-of-tree	75.87ms - 80.30ms	unsure 🔍 -4% - +4% -3.06ms - +3.28ms	-	unsure 🔍 -3% - +5% -2.02ms - +3.54ms
previous-release previous-release	75.65ms - 79.00ms	unsure 🔍 -4% - +3% -3.47ms - +2.17ms	unsure 🔍 -5% - +3% -3.54ms - +2.02ms	-

nop-update

Version	Avg time	vs this-change	vs tip-of-tree tip-of-tree	vs previous-release previous-release
this-change	16.21ms - 17.82ms	-	unsure 🔍 -4% - +8% -0.59ms - +1.36ms	unsure 🔍 -2% - +9% -0.29ms - +1.48ms
tip-of-tree tip-of-tree	16.08ms - 17.17ms	unsure 🔍 -8% - +3% -1.36ms - +0.59ms	-	unsure 🔍 -3% - +5% -0.46ms - +0.88ms
previous-release previous-release	16.04ms - 16.79ms	unsure 🔍 -9% - +2% -1.48ms - +0.29ms	unsure 🔍 -5% - +3% -0.88ms - +0.46ms	-

lit-html-repeat

Browser: chrome-headless 110.0.5481.177
Sample size: 30
Built by: Benchmarks #4481
Commit: 03db693

render

Version	Avg time	vs this-change	vs tip-of-tree tip-of-tree	vs previous-release previous-release
this-change	11.17ms - 11.97ms	-	unsure 🔍 -5% - +5% -0.62ms - +0.56ms	unsure 🔍 -5% - +5% -0.55ms - +0.63ms
tip-of-tree tip-of-tree	11.17ms - 12.03ms	unsure 🔍 -5% - +5% -0.56ms - +0.62ms	-	unsure 🔍 -5% - +6% -0.54ms - +0.69ms
previous-release previous-release	11.09ms - 11.96ms	unsure 🔍 -5% - +5% -0.63ms - +0.55ms	unsure 🔍 -6% - +5% -0.69ms - +0.54ms	-

update

Version	Avg time	vs this-change	vs tip-of-tree tip-of-tree	vs previous-release previous-release
this-change	259.28ms - 268.41ms	-	unsure 🔍 -3% - +2% -9.16ms - +4.29ms	unsure 🔍 -5% - +0% -12.72ms - +1.31ms
tip-of-tree tip-of-tree	261.34ms - 271.21ms	unsure 🔍 -2% - +3% -4.29ms - +9.16ms	-	unsure 🔍 -4% - +1% -10.54ms - +4.00ms
previous-release previous-release	264.22ms - 274.88ms	unsure 🔍 -1% - +5% -1.31ms - +12.72ms	unsure 🔍 -2% - +4% -4.00ms - +10.54ms	-

lit-html-template-heavy

Browser: chrome-headless 110.0.5481.177
Sample size: 50
Built by: Benchmarks #4481
Commit: 03db693

render

Version	Avg time	vs this-change	vs tip-of-tree tip-of-tree	vs previous-release previous-release
this-change	52.01ms - 53.98ms	-	unsure 🔍 -2% - +4% -0.89ms - +1.89ms	unsure 🔍 -2% - +3% -1.17ms - +1.61ms
tip-of-tree tip-of-tree	51.51ms - 53.48ms	unsure 🔍 -4% - +2% -1.89ms - +0.89ms	-	unsure 🔍 -3% - +2% -1.67ms - +1.11ms
previous-release previous-release	51.80ms - 53.75ms	unsure 🔍 -3% - +2% -1.61ms - +1.17ms	unsure 🔍 -2% - +3% -1.11ms - +1.67ms	-

update

Version	Avg time	vs this-change	vs tip-of-tree tip-of-tree	vs previous-release previous-release
this-change	104.47ms - 105.71ms	-	unsure 🔍 -0% - +1% -0.42ms - +1.24ms	unsure 🔍 -1% - +1% -1.02ms - +1.20ms
tip-of-tree tip-of-tree	104.12ms - 105.23ms	unsure 🔍 -1% - +0% -1.24ms - +0.42ms	-	unsure 🔍 -1% - +1% -1.39ms - +0.75ms
previous-release previous-release	104.08ms - 105.92ms	unsure 🔍 -1% - +1% -1.20ms - +1.02ms	unsure 🔍 -1% - +1% -0.75ms - +1.39ms	-

reactive-element-list

Browser: chrome-headless 110.0.5481.177
Sample size: 50
Built by: Benchmarks #4481
Commit: 03db693

render

Version	Avg time	vs this-change	vs tip-of-tree tip-of-tree	vs previous-release previous-release
this-change	53.62ms - 55.80ms	-	unsure 🔍 -4% - +2% -2.07ms - +0.87ms	unsure 🔍 -1% - +5% -0.66ms - +2.45ms
tip-of-tree tip-of-tree	54.32ms - 56.30ms	unsure 🔍 -2% - +4% -0.87ms - +2.07ms	-	unsure 🔍 -0% - +6% +0.01ms - +2.98ms
previous-release previous-release	52.71ms - 54.92ms	unsure 🔍 -4% - +1% -2.45ms - +0.66ms	faster ✔ 0% - 5% 0.01ms - 2.98ms	-

update

Version	Avg time	vs this-change	vs tip-of-tree tip-of-tree	vs previous-release previous-release
this-change	679.48ms - 685.72ms	-	unsure 🔍 -0% - +1% -2.98ms - +4.72ms	unsure 🔍 -0% - +1% -0.68ms - +6.53ms
tip-of-tree tip-of-tree	679.47ms - 683.99ms	unsure 🔍 -1% - +0% -4.72ms - +2.98ms	-	unsure 🔍 -0% - +1% -0.84ms - +4.95ms
previous-release previous-release	677.86ms - 681.49ms	unsure 🔍 -1% - +0% -6.53ms - +0.68ms	unsure 🔍 -1% - +0% -4.95ms - +0.84ms	-

update-reflect

Version	Avg time	vs this-change	vs tip-of-tree tip-of-tree	vs previous-release previous-release
this-change	711.21ms - 716.03ms	-	unsure 🔍 -1% - +0% -4.48ms - +2.87ms	unsure 🔍 -1% - +0% -4.44ms - +2.64ms
tip-of-tree tip-of-tree	711.65ms - 717.20ms	unsure 🔍 -0% - +1% -2.87ms - +4.48ms	-	unsure 🔍 -1% - +1% -3.89ms - +3.71ms
previous-release previous-release	711.92ms - 717.12ms	unsure 🔍 -0% - +1% -2.64ms - +4.44ms	unsure 🔍 -1% - +1% -3.71ms - +3.89ms	-

_{tachometer-reporter-action v2 for Benchmarks}

kevinpschaaf · 2023-02-11T01:22:24Z

packages/labs/analyzer/src/test/javascript/classes_test.ts

+  test('tagged description and summary', ({getModule}) => {
+    const dec = getModule('classes').getDeclaration('TaggedDescription');
+    assert.ok(dec.isClassDeclaration());
+    assert.equal(
+      dec.description,
+      `TaggedDescription description. Lorem ipsum dolor sit amet, consectetur
+adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna
+aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris
+nisi ut aliquip ex ea commodo consequat.`
+    );
+    assert.equal(dec.summary, `TaggedDescription summary.`);
+    assert.equal(dec.deprecated, `TaggedDescription deprecated message.`);
+  });
+
+  test('untagged description', ({getModule}) => {
+    const dec = getModule('classes').getDeclaration('UntaggedDescription');
+    assert.ok(dec.isClassDeclaration());
+    assert.equal(
+      dec.description,
+      `UntaggedDescription description. Lorem ipsum dolor sit amet, consectetur
+adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna
+aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris
+nisi ut aliquip ex ea commodo consequat.`
+    );
+    assert.equal(dec.summary, `UntaggedDescription summary.`);
+    assert.equal(dec.deprecated, `UntaggedDescription deprecated message.`);
+  });
+
+  // Fields
+
+  test('field1', ({getModule}) => {
+    const dec = getModule('classes').getDeclaration('Class1');
+    assert.ok(dec.isClassDeclaration());
+    const member = dec.getField('field1');
+    assert.ok(member?.isClassField());
+    assert.equal(
+      member.description,
+      `Class field 1 description\nwith wraparound`
+    );
+    assert.equal(member.default, `'default1'`);
+    assert.equal(member.privacy, 'private');
+    assert.equal(member.type?.text, 'string');
+  });
+
+  test('field2', ({getModule}) => {
+    const dec = getModule('classes').getDeclaration('Class1');
+    assert.ok(dec.isClassDeclaration());
+    const member = dec.getField('field2');
+    assert.ok(member?.isClassField());
+    assert.equal(member.summary, `Class field 2 summary\nwith wraparound`);
+    assert.equal(
+      member.description,
+      `Class field 2 description\nwith wraparound`
+    );
+    assert.equal(member.default, undefined);
+    assert.equal(member.privacy, 'protected');
+    assert.equal(member.type?.text, 'string | number');
+  });
+
+  test('field3', ({getModule}) => {
+    const dec = getModule('classes').getDeclaration('Class1');
+    assert.ok(dec.isClassDeclaration());
+    const member = dec.getField('field3');
+    assert.ok(member?.isClassField());
+    assert.equal(
+      member.description,
+      `Class field 3 description\nwith wraparound`
+    );
+    assert.equal(member.default, undefined);
+    assert.equal(member.privacy, 'public');
+    assert.equal(member.type?.text, 'string');
+    assert.equal(member.deprecated, true);
+  });
+
+  test('field4', ({getModule}) => {
+    const dec = getModule('classes').getDeclaration('Class1');
+    assert.ok(dec.isClassDeclaration());
+    const member = dec.getField('field4');
+    assert.ok(member?.isClassField());
+    assert.equal(member.summary, `Class field 4 summary\nwith wraparound`);
+    assert.equal(
+      member.description,
+      `Class field 4 description\nwith wraparound`
+    );
+    assert.equal(
+      member.default,
+      `new Promise${lang === 'ts' ? '<void>' : ''}((r) => r())`
+    );
+    assert.equal(member.type?.text, 'Promise<void>');
+    assert.equal(member.deprecated, 'Class field 4 deprecated');
+  });
+
+  test('static field1', ({getModule}) => {
+    const dec = getModule('classes').getDeclaration('Class1');
+    assert.ok(dec.isClassDeclaration());
+    const member = dec.getStaticField('field1');
+    assert.ok(member?.isClassField());
+    assert.equal(member.summary, `Static class field 1 summary`);
+    assert.equal(member.description, `Static class field 1 description`);
+    assert.equal(member.default, undefined);
+    assert.equal(member.privacy, 'protected');
+    assert.equal(member.type?.text, 'string | number');
+  });
+
+  // Methods
+
+  test('method1', ({getModule}) => {
+    const dec = getModule('classes').getDeclaration('Class1');
+    assert.ok(dec.isClassDeclaration());
+    const member = dec.getMethod('method1');
+    assert.ok(member?.isClassMethod());
+    assert.equal(member.description, `Method 1 description\nwith wraparound`);
+    assert.equal(member.parameters?.length, 0);
+    assert.equal(member.return?.type?.text, 'void');
+  });
+
+  test('method2', ({getModule}) => {
+    const dec = getModule('classes').getDeclaration('Class1');
+    assert.ok(dec.isClassDeclaration());
+    const member = dec.getMethod('method2');
+    assert.ok(member?.isClassMethod());
+    assert.equal(member.summary, `Method 2 summary\nwith wraparound`);
+    assert.equal(member.description, `Method 2 description\nwith wraparound`);
+    assert.equal(member.parameters?.length, 3);
+    assert.equal(member.parameters?.[0].name, 'a');
+    assert.equal(member.parameters?.[0].description, 'Param a description');
+    assert.equal(member.parameters?.[0].summary, undefined);
+    assert.equal(member.parameters?.[0].type?.text, 'string');
+    assert.equal(member.parameters?.[0].default, undefined);
+    assert.equal(member.parameters?.[0].rest, false);
+    assert.equal(member.parameters?.[1].name, 'b');
+    assert.equal(
+      member.parameters?.[1].description,
+      'Param b description\nwith wraparound'
+    );
+    assert.equal(member.parameters?.[1].type?.text, 'boolean');
+    assert.equal(member.parameters?.[1].optional, true);
+    assert.equal(member.parameters?.[1].default, 'false');
+    assert.equal(member.parameters?.[1].rest, false);
+    assert.equal(member.parameters?.[2].name, 'c');
+    assert.equal(member.parameters?.[2].description, 'Param c description');
+    assert.equal(member.parameters?.[2].summary, undefined);
+    assert.equal(member.parameters?.[2].type?.text, 'number[]');
+    assert.equal(member.parameters?.[2].optional, false);
+    assert.equal(member.parameters?.[2].default, undefined);
+    assert.equal(member.parameters?.[2].rest, true);
+    assert.equal(member.return?.type?.text, 'string');
+    assert.equal(member.return?.description, 'Method 2 return description');
+    assert.equal(member.deprecated, 'Method 2 deprecated');
+  });
+
+  test('static method1', ({getModule}) => {
+    const dec = getModule('classes').getDeclaration('Class1');
+    assert.ok(dec.isClassDeclaration());
+    const member = dec.getStaticMethod('method1');
+    assert.ok(member?.isClassMethod());
+    assert.equal(member.summary, `Static method 1 summary`);
+    assert.equal(member.description, `Static method 1 description`);
+    assert.equal(member.parameters?.length, 3);
+    assert.equal(member.parameters?.[0].name, 'a');
+    assert.equal(member.parameters?.[0].description, 'Param a description');
+    assert.equal(member.parameters?.[0].summary, undefined);
+    assert.equal(member.parameters?.[0].type?.text, 'string');
+    assert.equal(member.parameters?.[0].default, undefined);
+    assert.equal(member.parameters?.[0].rest, false);
+    assert.equal(member.parameters?.[1].name, 'b');
+    assert.equal(member.parameters?.[1].description, 'Param b description');
+    assert.equal(member.parameters?.[1].type?.text, 'boolean');
+    assert.equal(member.parameters?.[1].optional, true);
+    assert.equal(member.parameters?.[1].default, 'false');
+    assert.equal(member.parameters?.[1].rest, false);
+    assert.equal(member.parameters?.[2].name, 'c');
+    assert.equal(member.parameters?.[2].description, 'Param c description');
+    assert.equal(member.parameters?.[2].summary, undefined);
+    assert.equal(member.parameters?.[2].type?.text, 'number[]');
+    assert.equal(member.parameters?.[2].optional, false);
+    assert.equal(member.parameters?.[2].default, undefined);
+    assert.equal(member.parameters?.[2].rest, true);
+    assert.equal(member.return?.type?.text, 'string');
+    assert.equal(
+      member.return?.description,
+      'Static method 1 return description'
+    );
+    assert.equal(member.deprecated, 'Static method 1 deprecated');
+  });


All of these tests are moved unchanged from lit-element/jsdoc_test.js (and their duplicates that were in vanilla-element/jsdoc_test.js into here, so that this file is now all of the class-related tests.

The new tests are the const tests below, plus the superClass test, so that we have a superClass test in the basic class tests (there is another in the LitElement tests, so there was some coverage, but this makes sure it works for vanilla classes also).

kevinpschaaf · 2023-02-11T01:23:22Z

packages/labs/analyzer/src/test/javascript/modules_test.ts

+  // Doing module JSDoc tests in-memory, to test a number of variations
+  // without needing to maintain a file for each.
+
+  for (const hasFirstStatementDoc of [false, true]) {
+    const moduleTest = suite<{
+      analyzer: InMemoryAnalyzer;
+    }>(
+      `Module jsDoc tests, ${
+        hasFirstStatementDoc ? 'has' : 'no'
+      } first statement docs (${lang})`
+    );
+
+    moduleTest.before.each((ctx) => {
+      ctx.analyzer = new InMemoryAnalyzer(lang, {
+        '/package.json': JSON.stringify({name: '@lit-internal/in-memory-test'}),
+      });
+    });
+
+    const firstStatementDoc = hasFirstStatementDoc
+      ? `
+      /**
+       * First statement description
+       * @summary First statement summary
+       */
+    `
+      : '';
+
+    moduleTest('untagged module description with @module tag', ({analyzer}) => {
+      analyzer.setFile(
+        '/module',
+        `
+          /**
+           * Module description
+           * more description
+           * @module
+           */
+          ${firstStatementDoc}
+          export const foo = 42;
+        `
+      );
+      const module = analyzer.getModule(
+        getSourceFilename('/module', lang) as AbsolutePath
+      );
+      assert.equal(module.description, 'Module description\nmore description');
+    });
+
+    moduleTest(
+      'untagged module description with @fileoverview tag',
+      ({analyzer}) => {
+        analyzer.setFile(
+          '/module',
+          `
+          /**
+           * Module description
+           * more description
+           * @fileoverview
+           */
+          ${firstStatementDoc}
+          export const foo = 42;
+        `
+        );
+        const module = analyzer.getModule(
+          getSourceFilename('/module', lang) as AbsolutePath
+        );
+        assert.equal(
+          module.description,
+          'Module description\nmore description'
+        );
+      }
+    );
+
+    moduleTest('module description in @fileoverview tag', ({analyzer}) => {
+      analyzer.setFile(
+        '/module',
+        `
+          /**
+           * @fileoverview Module description
+           * more description
+           */
+          ${firstStatementDoc}
+          export const foo = 42;
+        `
+      );
+      const module = analyzer.getModule(
+        getSourceFilename('/module', lang) as AbsolutePath
+      );
+      assert.equal(module.description, 'Module description\nmore description');
+    });
+
+    moduleTest(
+      'untagged module description with @packageDocumentation tag',
+      ({analyzer}) => {
+        analyzer.setFile(
+          '/module',
+          `
+          /**
+           * Module description
+           * more description
+           * @packageDocumentation
+           */
+          ${firstStatementDoc}
+          export const foo = 42;
+        `
+        );
+        const module = analyzer.getModule(
+          getSourceFilename('/module', lang) as AbsolutePath
+        );
+        assert.equal(
+          module.description,
+          'Module description\nmore description'
+        );
+      }
+    );
+
+    moduleTest(
+      'module description in @packageDocumentation tag',
+      ({analyzer}) => {
+        analyzer.setFile(
+          '/module',
+          `
+          /**
+           * @packageDocumentation Module description
+           * more description
+           */
+          ${firstStatementDoc}
+          export const foo = 42;
+        `
+        );
+        const module = analyzer.getModule(
+          getSourceFilename('/module', lang) as AbsolutePath
+        );
+        assert.equal(
+          module.description,
+          'Module description\nmore description'
+        );
+      }
+    );
+
+    moduleTest(
+      'module description in @packageDocumentation tag with other tags',
+      ({analyzer}) => {
+        analyzer.setFile(
+          '/module',
+          `
+          /**
+           * @packageDocumentation Module description
+           * more description
+           * @module foo
+           * @deprecated Module is deprecated
+           */
+          ${firstStatementDoc}
+          export const foo = 42;
+        `
+        );
+        const module = analyzer.getModule(
+          getSourceFilename('/module', lang) as AbsolutePath
+        );
+        assert.equal(
+          module.description,
+          'Module description\nmore description'
+        );
+        assert.equal(module.deprecated, 'Module is deprecated');
+      }
+    );
+
+    moduleTest('untagged module description', ({analyzer}) => {
+      analyzer.setFile(
+        '/module',
+        `
+          /**
+           * Module description
+           * more module description
+           * @summary Module summary
+           * @deprecated
+           */
+          /**
+           * First statement description
+           * @summary First statement summary
+           */
+          export const foo = 42;
+        `
+      );
+      const module = analyzer.getModule(
+        getSourceFilename('/module', lang) as AbsolutePath
+      );
+      assert.equal(
+        module.description,
+        'Module description\nmore module description'
+      );
+      assert.equal(module.summary, 'Module summary');
+      assert.equal(module.deprecated, true);
+    });
+
+    moduleTest('multiple untagged module descriptions', ({analyzer}) => {
+      analyzer.setFile(
+        '/module',
+        `
+          /**
+           * Module description
+           * more module description
+           */
+          /**
+           * Even more module description
+           */
+          /**
+           * First statement description
+           * @summary First statement summary
+           */
+          export const foo = 42;
+        `
+      );
+      const module = analyzer.getModule(
+        getSourceFilename('/module', lang) as AbsolutePath
+      );
+      assert.equal(
+        module.description,
+        'Module description\nmore module description\nEven more module description'
+      );
+    });
+
+    moduleTest(
+      'multiple untagged module descriptions with other tags',
+      ({analyzer}) => {
+        analyzer.setFile(
+          '/module',
+          `
+          /**
+           * Module description
+           * more module description
+           * @deprecated
+          */
+          /**
+           * Even more module description
+           * @summary Module summary
+           */
+          /**
+           * First statement description
+           * @summary First statement summary
+           */
+          export const foo = 42;
+        `
+        );
+        const module = analyzer.getModule(
+          getSourceFilename('/module', lang) as AbsolutePath
+        );
+        assert.equal(
+          module.description,
+          'Module description\nmore module description\nEven more module description'
+        );
+        assert.equal(module.summary, 'Module summary');
+        assert.equal(module.deprecated, true);
+      }
+    );


Moved from lit-element/jsdoc_tests.js

kevinpschaaf · 2023-02-11T01:24:24Z

packages/labs/analyzer/src/test/vanilla-element/jsdoc_test.ts

-  });
-
-  test('field4', ({getModule}) => {
+  test('basic class analysis', ({getModule}) => {


Moved all the class-specific stuff to classes_test.js, and just left a basic class analysis test here.

bicknellr · 2023-02-13T19:42:47Z

packages/labs/analyzer/src/lib/javascript/classes.ts

+ * Note, the `docNode` may differ from the `declaration` in
+ * the case of a const assignment to a class expression, as
+ * the docs will be on the VariableStatement rather than
+ * the class-like expression.


There's a getJSDocTags function in the TS repo where the docs claim it gets related JSDoc tags even if they're on other nodes. Would that work here?

parseNodeJSDocInfo uses that here:

lit/packages/labs/analyzer/src/lib/javascript/jsdoc.ts

Line 242 in 05b6dd5

const jsDocTags = ts.getJSDocTags(node);

But it doesn't seem to return the e.g. @description, etc. tag on the parent variable statement when the node passed to it is the class expression initializer.

Oddly it does do the thing you expected for const functions, just not for const classes. I had made the equivalent API's between classes and functions line up (i.e. take an optional docNode), but seems like it's not strictly required for functions for whatever reason. I guess I'll yank that back out of the function side...

bicknellr · 2023-02-13T19:59:55Z

packages/labs/analyzer/src/lib/javascript/variables.ts

+  statement: ts.VariableStatement,
  dec: ts.VariableDeclaration | ts.EnumDeclaration,


I think statement can be retrieved from a VariableDeclaration with .parent.parent. Also, what is statement's relationship to dec when dec is an EnumDeclaration?

Oh, I just noticed there's a getEnumDeclaration and getEnumDeclarationInfo below. Does getVariableDeclaration need to handle both VariableDeclarations and EnumDeclarations?

Ah, the EnumDeclaration in that union was vestigial; prior to this getDeclarationInfo handled both variables and enums, but after introducing the statement arg, I had to split them out. Removed.

I think statement can be retrieved from a VariableDeclaration with .parent.parent.

Oh yeah good point. Hmm, it'd need to be cast though, since VariableDeclaration can exist in for/for of/for in statements also. Feels a little stricter as-is?

What about checking if .parent.parent is a VariableStatement?

packages/labs/analyzer/src/lib/javascript/variables.ts

kevinpschaaf added 2 commits February 10, 2023 16:58

Support const function/class declarations

f68d31c

Add back basic class analysis to CE tests

c4ecd9d

kevinpschaaf requested a review from bicknellr February 11, 2023 01:16

kevinpschaaf requested a review from justinfagnani as a code owner February 11, 2023 01:16

Move module jsdoc tests to module tests

05b6dd5

kevinpschaaf commented Feb 11, 2023

View reviewed changes

bicknellr reviewed Feb 13, 2023

View reviewed changes

Address review feedback.

afd1c08

kevinpschaaf requested a review from bicknellr February 14, 2023 02:20

Add and fix tests around const declaration docs

e3628bc

bicknellr approved these changes Feb 15, 2023

View reviewed changes

Merge branch 'main' into analyzer-const-class-fn

c2f29ed

kevinpschaaf merged commit cabc618 into main Mar 3, 2023

kevinpschaaf deleted the analyzer-const-class-fn branch March 3, 2023 00:34

lit-robot mentioned this pull request Mar 10, 2023

Version Packages #3717

Merged

		statement: ts.VariableStatement,
		dec: ts.VariableDeclaration \| ts.EnumDeclaration,

Conversation

kevinpschaaf commented Feb 11, 2023 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

changeset-bot bot commented Feb 11, 2023 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

🦋 Changeset detected

Uh oh!

github-actions bot commented Feb 11, 2023 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

📊 Tachometer Benchmark Results

Summary

nop-update

render

update

update-reflect

Results

render

update

update-reflect

render

update

nop-update

render

update

render

update

render

update

update-reflect

Uh oh!

kevinpschaaf Feb 11, 2023 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

kevinpschaaf commented Feb 11, 2023 •

edited

Loading

changeset-bot bot commented Feb 11, 2023 •

edited

Loading

github-actions bot commented Feb 11, 2023 •

edited

Loading

kevinpschaaf Feb 11, 2023 •

edited

Loading