Documenting custom elements

[andyearnshaw]

We have an API we provide to 3rd-parties, for which I've written a custom HTML elements (document.register) polyfill and a handful of custom elements, with more on the way. We're currently using YUIDoc to document the rest of the API, but I'd also like to document these custom elements, along with their attributes and behaviour, in their own section (ie, next to Classes and Modules). Is this currently possible?

Being able to write something like this would be great:

/**
 * Provides a x-foo for a y-bar
 * @element x-foo
 * @attribute baz includes a baz
 * @attribute qux what the qux will look like
 */

[lexander]

This is an interesting request, with web components adding their custom HTML elements to pages, I expect that there will be other similar requests in the future.

Currently, I don't see an easy way to add real support for custom elements. It seems like this would need to be a new primary tag ala @class or @module and that changes would need to be made to both the parsing engine and output templates.

Would using the @class tag and prefixing your custom elements with a string like element- work in the short term? That would cause them to all be shown in a group under the Classes tab of the output files.

[andyearnshaw]

I did plan on using the @class tag for the short term, it's just more difficult to mark up attributes as properties.

I've almost found success writing @class <x-foo>, XFooElement, but for some reason the output prefixes all my class names with the main namespace (which I never noticed before, because all the class names were part of the main namespace).

[okuryu]

I've just seen a similar question recently.
http://stackoverflow.com/questions/29063774/yuidocs-parse-polymer-element

I'm not familiar with Web Components for now, so I'm not sure what is best way for this. However, I feel it's interesting improvements, I'd love to do it if there is a thing that I can!

[andyearnshaw]

Well I'm glad to see there's interest here! Here's some things in particular that I'd like to document for each of my custom elements that currently have no semantic YUIDoc attribute:

• Permitted child elements
• Permitted parent elements
• Matching class/constructor interface
• Attributes

The first three of those could cross link automatically, kind of like how the MDN documentation is for elements.

[andyearnshaw]

We're looking at allocating some time to this in the near future as it is becoming more important to us as we expand the custom elements provided by our API. Do you have any thoughts on how we should proceed before we start?

[okuryu]

@andyearnshaw I haven't started a specific work yet, and I feel that I need to become more familiar with Web Components and Polymer world. Anyway, I'm welcome your contributions at anytime. 👍

[andyearnshaw]

I've just started work on this and already hit a snag! @attribute is an existing tag and maps to @property internally (though the docs say that it's a YUI-specific tag). Changing it would obviously introduce a compatibility issue, and a conflict in the following case:

/**
 * The interface for an <x-foo> element.
 * @class XFooElement
 */
/**
 * Renders a foo.
 * @element x-foo
 */
var XFooElement = document.registerElement( ...args );

/**
 * Gets or sets the bar.
 * @property {string} bar
 */
/**
 * Sets the bar.  Linked to the property of the same name.
 * @attribute bar
 */
Object.defineProperty(XFooElement.prototype, 'bar', { ... });

How should @attribute behave in this case? I could introduce a new tag (e.g. @attr) to resolve this problem, but that might be confusing to people and cause problems when no warnings or errors are generated.

Some advice on how to proceed here would be great! 🙏

[okuryu]

I would like to maintain a backward compatibility, and I prefer using @attribute tag rather than adding a new tag like @attr. We can handle behavior of @attribute tag by the presence or absence of @element tag.

[okuryu]

#371 have been merged. This feature will be available in the next version.