RE: [webcomponents] self-documenting component.html files

For the attribute changes, you can use MutationObservers, unless you need to have the values updated synchronously, in which case, you can always fallback to Mutation Events or hook the relevant APIs with ES5 defineProperty overrides…? Generally, I think all the tools you need for notifications are probably already available.

From: Mike Kamermans [mailto:nihongo@gmail.com]
Sent: Friday, April 5, 2013 4:51 AM
To: public-webapps@w3.org
Subject: [webcomponents] self-documenting component.html files

Hi all,

a short while back I'd been working on a web components demo, with one result being a components.html that also acted as its own documentation (since as a components.html anything that isn't 'more components', script, or element, gets ignored), which sparked a small discussion on how self-documentation might be done at all. I've been trying to think of some way to do this while staying within the custom element specification, but I keep ending up with needing bits that aren't in the spec. So, let me just list what I have, and perhaps some of the bits are useful enough for further discussion, while some other bits can be shown to be silly, with much better alternatives. This is what I come up with if the idea is to make a custom element as self-descriptive as possible:https://gist.github.com/Pomax/5304557


One obvious difference is that for attributes that you actually want to do anything with (i.e., you're creating your own custom audio element, and setting the src should reload the data and start autoplaying or something), you want to be able to specify the getter/setter and events that will occur. I didn't see anything in the webcomponents/custom element specs that would currently allow for this. I did hear from Scott Miles that some work had already been done, and that the custom element shim now already supports an attributeChangedCallback function to do just this thing, but that's a bit broader level than specific get/set behaviour on attributes. Consider my gist to be some thinking out loud =)

Also, out of the discussion on fully documenting vs. docstripped (essentially the develop vs. production question): I'd make this something that people who deploy their components for others to use are responsible for in the same way they are responsible for full vs. minified javascript libraries right now. If you only put up a fully-documented components.html you're probably inconveniencing your audience, but having it available next to a minified version is great for when people want to look something up - they'll know where to go by simply removing the ".min" part in a CND'ed components.html URL. So as long as the minification process is easily performed, that should be enough (so my gist also contains a description of what "minification" would look like)

- Mike "Pomax" Kamermans