@customElement / @element quirks in JSDocBlock

[btopro]

The analyzer currently seems to be looking for the static tag name as supplied in the customElements.define("what-ever", WhatEver);

If this is generated off the class itself or defined elsewhere this can cause issues causing an empty output for the tag name. Possible solutions:

• if empty, look for .tag off of the element, convention I've seen used elsewhere even though its not part of the spec
• support an argument being passed in via CLI that defines the tag

Referencing a commit on this to see what generated blank though I'm sure almost all our elements will since we use this convention.

[runem]

Adding @element my-element to the jsdoc of the class declaration is currently support. Does that work in your case? :-)

[btopro]

silly me. thanks for pointing int he right direction. apparently @customElement was being picked up and that set it to nothing since I didn't have it defined anywhere :p fixing tooling now. thank you https://github.com/elmsln/lrnwebcomponents/commit/e7e655961ccb07b795d79b2cb8bbdb0f0dc58a7a#diff-fda6e8bbad7776d2307dcafcbaf9ec9dR32

[btopro]

last thing. is it an issue if @element is defined at the top of the JSdocblock? I'm noticing that if its not at the very bottom of the docblock that it doesn't document it correctly. Example: https://github.com/elmsln/lrnwebcomponents/blob/master/elements/video-player/video-player.js#L15

leads to this:

https://github.com/elmsln/lrnwebcomponents/blob/master/elements/video-player/custom-elements.json#L5

[runem]

It seems like the @customElement jsdoc tag is parsed as name including the next line, even though the next line should be the description related to the jsdoc tag.

/**
 * @customElement video-player
 * `A simple responsive video player with ridiculously powerful backing`
 * ...
 */
class VideoPlayer ...

I'm currently working on finishing up version 1.0.0, and this version includes much better jsdoc support. I tested it on video-player.js and it seems to work fine. Below I added what v1.0.0 of the analyzer outputs using markdown output format :-)

In addition, you don't have to add @customElement video-player when using the v1.0.0, because the analyzer is now able to resolve the value of simple expressions like VideoPlayer.tag.

I expect the major version to land soon, and you can test the beta version like this:

npx web-component-analyzer@1.0.0-next.3 analyze video-player.js

I tried cloning elmsln/lrnwebcomponents and installing 1.0.0-next.3. It seemed like it successfully found the correct name of all elements. However, I saw that there were multiple elements with the same name in many custom-elements.json this is because the analyzer finds the same element in multiple files (eg. from .es6 and .umd). Therefore I suggest you to change the glob from this && wca analyze \"**/*.js\" --outFile custom-elements.json to something this && wca analyze \"!(*.umd|*.story|gulpfile|rollup.config|*.es6).js\" --outFile custom-elements.json :-)

If you like, you can also run the command with this glob from the root of the mono-repo in order to generate markdown documentation for all files at the same time:

npx web-component-analyzer@1.0.0-next.3 analyze "./elements/**/!(*.umd|*.story|gulpfile|rollup.config|*.es6).js"

video-player

Mixins: MediaBehaviorsVideo, A11yBehaviors, SchemaBehaviors

Properties

Property	Attribute	Type	Default	Description
accentColor	accent-color	string	null	Optional accent color for controls, using the following materialize "colors": red, pink, purple, deep-purple, indigo, blue, light blue, cyan, teal, green, light green, lime, yellow, amber, orange, deep-orange, and brown. Default is null.
audioOnly	audio-only	boolean	false	Is the media an audio file only?
crossorigin	crossorigin	string	null	Cross origin flag for transcripts to load
dark	dark	boolean	false	Enables darker player.
darkTranscript	dark-transcript	boolean	false	Use dark theme on transcript? Default is false, even when player is dark.
disableInteractive	disable-interactive	boolean	false	disable interactive mode that makes the transcript clickable
height	height	string	null	The height of the media player for non-a11y-media.
hideTimestamps	hide-timestamps	boolean	false	show cue's start and end time
hideTranscript	hide-transcript	boolean	false	hide the transcript by default
iframed	iframed	boolean		Computed if this should be in an iframe or not.
isA11yMedia	is-a11y-media	boolean		Computed if this should be in a11y-media-player.
isYoutube	is-youtube	boolean		The type of source, i.e. "local", "vimeo", "youtube", etc.
lang	lang	string	"en"	The language of the media
linkable	linkable	boolean	false	Include a share link?
mediaTitle	media-title	string		Simple caption for the video
playerId	player-id	string	null	ID for a11y-media-player. If none specified it will be modified from schema-resource-id.
preload	preload	string	"metadata"	What to preload for a11y-media-player: auto, metadata (default), or none.
sandboxed	sandboxed	boolean		Compute if this is a sandboxed system or not
source	source	string	null	Source of the video
sourceData	source-data	array		List of source objects
sourceType	source-type	string		The type of source, i.e. "local", "vimeo", "youtube", etc.
sources	sources	array		Source of the video
stickyCorner	sticky-corner	string	"top-right"	When playing but scrolled off screen, to which corner does it "stick": top-left, top-right, bottom-left, bottom-right, or none? Default is "top-right". "None" disables stickiness.
thumbnailSrc	thumbnail-src	string	null	Source of optional thumbnail image
track	track	string	null	The url for a single subtitle track
trackData	track-data	array		Cleaned array of text tracks [{ "src": "path/to/track.vtt", "label": "English", "srclang": "en", "kind": "subtitles", }]
tracks	tracks	array		Array of text tracks [{ "src": "path/to/track.vtt", "label": "English", "srclang": "en", "kind": "subtitles", }]
width	width	string	null	The width of the media player for non-a11y-media.
youtubeId	youtube-id	string		The type of source, i.e. "local", "vimeo", "youtube", etc.

Methods

Method	Description
postProcesshaxNodeToContent	postProcesshaxNodeToContent - clean up so we don't have empty array data

[btopro]

excellent to hear! thank you @runem for following up