jpradelle
commented
2 years ago I took freedom to update the pull request to add a 2nd feature: add a parameter on CLI to configure classes to exclude during parsing, feature was already implemented but not available on CLI.
Analysis of Polymer custom components reports Polymer super class related properties and functions.
The pull request adds ignore of this super class to get only component defined properties and function like with Polymer provided tooling.
Example of analyzed source
```js import {PolymerElement, html} from '@polymer/polymer/polymer-element'; /** * @polymer * @customElement * * @fires test-event My super custom event */ export class PolymerTest2 extends PolymerElement { static get properties() { /** * @lends PolymerTest2.prototype */ return { /** * Test plop property * @type {string} */ testPlop: { type: String }, /** * Test plopp property * @type {number} */ testPlopp: { type: Number, value: 1 } }; } static get template() { // language=HTML return html` [[testPlop]] - [[testPlopp]] `; } } customElements.define('polymer-test2', PolymerTest2); ```Markdown result with pull request code
# polymer-test2 ## Properties | Property | Attribute | Type | Default | Description | |-------------|--------------|----------|---------|---------------------| | `testPlop` | `test-plop` | `string` | | Test plop property | | `testPlopp` | `test-plopp` | `number` | 1 | Test plopp property | ## Events | Event | Description | |--------------|-----------------------| | `test-event` | My super custom event |Markdown result without pull request code
# polymer-test2 **Mixins:** ElementMixin ## Properties | Property | Attribute | Modifiers | Type | Default | Description | |-------------------------|--------------|-----------|--------------------------------------------------|---------|---------------------| | `$` | | | `{ [key: string]: Element; }` | | | | `PROPERTY_EFFECT_TYPES` | | readonly | | | | | `importPath` | | | `string` | | | | `root` | | | `HTMLElement \| StampedTemplate \| ShadowRoot \| null` | | | | `rootPath` | | | `string` | | | | `testPlop` | `test-plop` | | `string` | | Test plop property | | `testPlopp` | `test-plopp` | | `number` | 1 | Test plopp property | ## Methods | Method | Type | Description | |---------------------------------|--------------------------------------------------|--------------------------------------------------| | `addPropertyEffect` | `(property: string, type: string, effect?: object \| null \| undefined): void` | Ensures an accessor exists for the specified property, and addsto a list of "property effects" that will run when the accessor for
the specified property is set. Effects are grouped by "type", which
roughly corresponds to a phase in effect processing. The effect
metadata should be in the following form:
{
fn: effectFunction, // Reference to function to call to perform effect
info: { ... } // Effect metadata passed to function
trigger: { // Optional triggering metadata; if not provided
name: string // the property is treated as a wildcard
structured: boolean
wildcard: boolean
}
}
Effects are called from `_propertiesChanged` in the following order by
type:
1. COMPUTE
2. PROPAGATE
3. REFLECT
4. OBSERVE
5. NOTIFY
Effect functions are called with the following signature:
effectFunction(inst, path, props, oldProps, info, hasPaths)
**property**: Property that should trigger the effect
**type**: Effect type, from this.PROPERTY_EFFECT_TYPES
**effect**: Effect metadata object | | `attributeNameForProperty` | `(property: string): string` | Returns an attribute name that corresponds to the given property.
By default, converts camel to dash case, e.g. `fooBar` to `foo-bar`.
**property**: Property to convert | | `bindTemplate` | `(template: HTMLTemplateElement): TemplateInfo` | Parses the provided template to ensure binding effects are created
for them, and then ensures property accessors are created for any
dependent properties in the template. Binding effects for bound
templates are stored in a linked list on the instance so that
templates can be efficiently stamped and unstamped.
**template**: Template containing binding
bindings | | `createComputedProperty` | `(property: string, expression: string, dynamicFn?: boolean \| object \| null \| undefined): void` | Creates a computed property whose value is set to the result of the
method described by the given `expression` each time one or more
arguments to the method changes. The expression should be a string
in the form of a normal JavaScript function signature:
`'methodName(arg1, [..., argn])'`
**property**: Name of computed property to set
**expression**: Method expression
**dynamicFn**: Boolean or object map indicating whether
method names should be included as a dependency to the effect. | | `createMethodObserver` | `(expression: string, dynamicFn?: boolean \| object \| null \| undefined): void` | Creates a multi-property "method observer" based on the provided
expression, which should be a string in the form of a normal JavaScript
function signature: `'methodName(arg1, [..., argn])'`. Each argument
should correspond to a property or path in the context of this
prototype (or instance), or may be a literal string or number.
**expression**: Method expression
**dynamicFn**: Boolean or object map indicating | | `createNotifyingProperty` | `(property: string): void` | Causes the setter for the given property to dispatch `
events to notify of changes to the property.
**property**: Property name | | `createObservers` | `(observers: object \| null, dynamicFns: object \| null): void` | Creates observers for the given `observers` array.
Leverages `PropertyEffects` to create observers.
**observers**: Array of observer descriptors for
this class
**dynamicFns**: Object containing keys for any properties
that are functions and should trigger the effect when the function
reference is changed | | `createProperties` | `(props: object): void` | Override of PropertiesChanged createProperties to create accessors
and property effects for all of the properties.
**props**: . | | `createPropertiesForAttributes` | `(): void` | Generates property accessors for all attributes in the standard
static `observedAttributes` array.
Attribute names are mapped to property names using the `dash-case` to
`camelCase` convention | | `createPropertyObserver` | `(property: string, method: string \| ((p0: any, p1: any): any), dynamicFn?: boolean \| undefined) => void` | Creates a single-property observer for the given property.
**property**: Property name
**method**: Function or name of observer method to call
**dynamicFn**: Whether the method name should be included as
a dependency to the effect. | | `createReadOnlyProperty` | `(property: string, protectedSetter?: boolean \| undefined): void` | Creates a read-only accessor for the given property.
To set the property, use the protected `_setProperty` API.
To create a custom protected setter (e.g. `_setMyProp()` for
property `myProp`), pass `true` for `protectedSetter`.
Note, if the property will have other property effects, this method
should be called first, before adding other effects.
**property**: Property name
**protectedSetter**: Creates a custom protected setter
when `true`. | | `createReflectedProperty` | `(property: string): void` | Causes the setter for the given property to reflect the property value
to a (dash-cased) attribute of the same name.
**property**: Property name | | `finalize` | `(): void` | Finalizes an element definition, including ensuring any super classes
are also finalized. This includes ensuring property
accessors exist on the element prototype. This method calls
`_finalizeClass` to finalize each constructor in the prototype chain. | | `get` | `(path: string \| (string \| number)[], root?: object \| null \| undefined): any` | Convenience method for reading a value from a path.
Note, if any part in the path is undefined, this method returns
`undefined` (this method does not throw when dereferencing undefined
paths).
**path**: Path to the value
to read. The path may be specified as a string (e.g. `foo.bar.baz`)
or an array of path parts (e.g. `['foo.bar', 'baz']`). Note that
bracketed expressions are not supported; string-based path parts
*must* be separated by dots. Note that when dereferencing array
indices, the index may be used as a dotted part directly
(e.g. `users.12.name` or `['users', 12, 'name']`).
**root**: Root object from which the path is evaluated. | | `linkPaths` | `(to: string \| (string \| number)[], from: string \| (string \| number)[]): void` | Aliases one data path as another, such that path notifications from one
are routed to the other.
**to**: Target path to link.
**from**: Source path to link. | | `notifyPath` | `(path: string, value?: any): void` | Notify that a path has changed.
Example:
this.item.user.name = 'Bob';
this.notifyPath('item.user.name');
**path**: Path that should be notified.
**value**: Value at the path (optional). | | `notifySplices` | `(path: string, splices: any[] \| null): void` | Notify that an array has changed.
Example:
this.items = [ {name: 'Jim'}, {name: 'Todd'}, {name: 'Bill'} ];
...
this.items.splice(1, 1, {name: 'Sam'});
this.items.push({name: 'Bob'});
this.notifySplices('items', [
{ index: 1, removed: [{name: 'Todd'}], addedCount: 1,
object: this.items, type: 'splice' },
{ index: 3, removed: [], addedCount: 1,
object: this.items, type: 'splice'}
]);
**path**: Path that should be notified.
**splices**: Array of splice records indicating ordered
changes that occurred to the array. Each record should have the
following fields:
* index: index at which the change occurred
* removed: array of items that were removed from this index
* addedCount: number of new items added at this index
* object: a reference to the array in question
* type: the string literal 'splice'
Note that splice records _must_ be normalized such that they are
reported in index order (raw results from `Object.observe` are not
ordered and must be normalized/merged before notifying). | | `pop` | `(path: string \| (string \| number)[]): any` | Removes an item from the end of array at the path specified.
The arguments after `path` and return value match that of
`Array.prototype.pop`.
This method notifies other paths to the same array that a
splice occurred to the array.
**path**: Path to array. | | `push` | `(path: string \| (string \| number)[], ...items: any[]): number` | Adds items onto the end of the array at the path specified.
The arguments after `path` and return value match that of
`Array.prototype.push`.
This method notifies other paths to the same array that a
splice occurred to the array.
**path**: Path to array.
**items**: Items to push onto array | | `ready` | `(): void` | Stamps the element template. | | `resolveUrl` | `(url: string, base?: string \| undefined): string` | Rewrites a given URL relative to a base URL. The base URL defaults to
the original location of the document containing the `dom-module` for
this element. This method will return the same URL before and after
bundling.
Note that this function performs no resolution for URLs that start
with `/` (absolute URLs) or `#` (hash identifiers). For general purpose
URL resolution, use `window.URL`.
**url**: URL to resolve.
**base**: Optional base URL to resolve against, defaults
to the element's `importPath` | | `set` | `(path: string \| (string \| number)[], value: any, root?: object \| null \| undefined): void` | Convenience method for setting a value to a path and notifying any
elements bound to the same path.
Note, if any part in the path except for the last is undefined,
this method does nothing (this method does not throw when
dereferencing undefined paths).
**path**: Path to the value
to write. The path may be specified as a string (e.g. `'foo.bar.baz'`)
or an array of path parts (e.g. `['foo.bar', 'baz']`). Note that
bracketed expressions are not supported; string-based path parts
*must* be separated by dots. Note that when dereferencing array
indices, the index may be used as a dotted part directly
(e.g. `'users.12.name'` or `['users', 12, 'name']`).
**value**: Value to set at the specified path.
**root**: Root object from which the path is evaluated.
When specified, no notification will occur. | | `setProperties` | `(props: object \| null, setReadOnly?: boolean \| undefined): void` | Sets a bag of property changes to this instance, and
synchronously processes all effects of the properties as a batch.
Property names must be simple properties, not paths. Batched
path propagation is not supported.
**props**: Bag of one or more key-value pairs whose key is
a property and value is the new value to set for that property.
**setReadOnly**: When true, any private values set in
`props` will be set. By default, `setProperties` will not set
`readOnly: true` root properties. | | `shift` | `(path: string \| (string \| number)[]): any` | Removes an item from the beginning of array at the path specified.
The arguments after `path` and return value match that of
`Array.prototype.pop`.
This method notifies other paths to the same array that a
splice occurred to the array.
**path**: Path to array. | | `splice` | `(path: string \| (string \| number)[], start: number, deleteCount?: number \| undefined, ...items: any[]): any[]` | Starting from the start index specified, removes 0 or more items
from the array and inserts 0 or more new items in their place.
The arguments after `path` and return value match that of
`Array.prototype.splice`.
This method notifies other paths to the same array that a
splice occurred to the array.
**path**: Path to array.
**start**: Index from which to start removing/inserting.
**deleteCount**: Number of items to remove.
**items**: Items to insert into array. | | `typeForProperty` | `(name: string): void` | Override point to provide a type to which to deserialize a value to
a given property.
**name**: Name of property | | `unlinkPaths` | `(path: string \| (string \| number)[]): void` | Removes a data path alias previously established with `_linkPaths`.
Note, the path to unlink should be the target (`to`) used when
linking the paths.
**path**: Target path to unlink. | | `unshift` | `(path: string \| (string \| number)[], ...items: any[]): number` | Adds items onto the beginning of the array at the path specified.
The arguments after `path` and return value match that of
`Array.prototype.push`.
This method notifies other paths to the same array that a
splice occurred to the array.
**path**: Path to array.
**items**: Items to insert info array | | `updateStyles` | `(properties?: object \| null \| undefined): void` | When using the ShadyCSS scoping and custom property shim, causes all
shimmed styles in this element (and its subtree) to be updated
based on current custom property values.
The optional parameter overrides inline custom property styles with an
object of properties where the keys are CSS properties, and the values
are strings.
Example: `this.updateStyles({'--color': 'blue'})`
These properties are retained unless a value of `null` is set.
Note: This function does not support updating CSS mixins.
You can not dynamically change the value of an `@apply`.
**properties**: Bag of custom property key/values to
apply to this element. | ## Events | Event | Description | |--------------|-----------------------| | `test-event` | My super custom event |