[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