Proposal: Self Documenting Custom Elements

[Eric Bidelman]

Inspired by Mike K's great idea of self documenting custom elements, I've written a proposal to formalize the effort.

We have a great opportunity here to come up with best practices early on.

Proposal: Self Documenting Custom Elements

    - prototype - a custom element that uses this method.

    - it's <wc-documentation> (best viewed in Chrome Canary to get ::distributed()).

Things I like about this approach:

- The delivery mechanism is <link rel="import">. 

- Becomes the "view source of custom elements". Click an import's link -> get its docs.

- The docs themselves are custom elements

- works reasonably well in other modern browsers, especially if the toolkit polyfills are included.

Looking for everyone's feedback. 

Eric Bidelman

[Dimitri Glazkov]

This is a beautiful vision. I agree with the all the concerns you raised and hope that we could address them. Also (possibly a terrible idea) -- would it be useful to use WebIDL to document the imperative API? Then, we can use something like ReSpec to automatically and consistently build the table of properties/methods.

Also -- how do we document markup API?

:DG<

[Mike Kamermans]

Love the effort to get this right, but it looks like the proposed wc-documentation element is going to live entirely separated from the actual elements... documentation is way better than no documentation, but self-documentation would be much nicer than plain documentation. I'll need to read it in more detail when I get a bit more time hopefully today or later this week, but I think we can raise the bar here =)

- Mike

[Eric Bidelman]

Dimitri,

WebIDL might be worth investigating. I just worry the more layers we add to this,

the higher the barrier to entry, and the less likely people will actually care 

Thanks Mike.

I do like the inline approach as you have it, but I'm a firm believer

in keeping <element> source as clean as possible. Anything we do with

docs should annotate an element rather than mixing in extra bloat. Maybe this is just me?

In the future, I imagine inline screenshots, demos, other stylesheets....Everything lends itself

very nicely to Shadow DOM and a custom element. Self-documenting in the since that you can

read about the element by viewing it's import. It doesn't mean the doc needs to be inlined.

Of course, build steps can remove all these extra goodies. However, if I've learned one thing

over the last couple of years, it's that many front end developers still don't have a build step :(

[Randy Merrill]

+1 Keeping the actual <element> source as clean as possible without needing a build tool to pull out the extra meta.

[Erik Arvidsson]

I like the idea behind this but having to repeat things will lead to
inconsistencies, whether the API is written in WebIDL (god forbid) or
in a separate document.

Based on that I'm in favor of plain old JSDoc.

On Mon, Apr 8, 2013 at 6:39 PM, Randy Merrill <randym...@google.com> wrote:
> +1 Keeping the actual <element> source as clean as possible without needing
> a build tool to pull out the extra meta.
>

> --
> You received this message because you are subscribed to the Google Groups
> "Toolkitchen" group.
> To unsubscribe from this group and stop receiving emails from it, send an
> email to toolkitchen...@googlegroups.com.
> For more options, visit https://groups.google.com/groups/opt_out.
>
>



--
erik

[Eric Bidelman]

Keeping docs in sync with code is a challenge that exists today and sadly

won't go away with web components.

I think JSDoc is ideal if you're looking at code, but I'm not sure it's right for something like this.

We have an 6+ headed beast: markup, styling, events, attributes, dependancies, and examples.

[Mike Kamermans]

Just wondering why you'd want to keep <element> as clean as possible. From a developer point of view, keeping it clean but having the docs detached feels like a minefield, for an end user the views I'd care about are the presentation (in which case the actual HTML doesn't particularly matter since I'm not looking at it) and the function when I import it (and then I don't even care about what's in the file, it just has to do what it claimed it'd do).

I do love clean code, but for documentation purposes I also like idea of "adding documentation in the <element> if I want to do that, and have it act as an autodocumentation". If I have an <element attributes="start"> and I add a <wc-documentation> element in which I explain it uses attributes "href" and "title", that's problematic. Validators will have to get more complex if they want to validate that the docs are in sync with the actual definitions, too, that way. In terms of accountability, I'd strongly prefer in-element annotation, even if it "bulks up" the defitions. It can be done in-element but also cleanly! Just not trivially.

I can see the argument that having to run a build step to strip the docs is a hassle, but docs shouldn't be mandatory, so if you don't want to document (and the same argument then goes for if we go the detached-docs route, you'd still need to run a build step to strip it out, same as for in-element docs), don't document. It should work irrespective of whether someone made the documentation effort (plenty of people will end up not documenting =)

- Mike

[Addy Osmani]

Picking up on this thread from last year:

For a developer looking to document the elements they're authoring today, do we have an answer we can give them? (I've read through Eric's self-documenting proposal and agree, it's a beautiful vision).

After playing around with the prototype, however it looks like we would need to either agree on an initial base template / format for the documentation element or punt to existing tools like JSDoc (which Eric has already mentioned has it's own issues as we're dealing with a multi-headed beast).

I'm primarily interested in this for Polymer tooling/boilerplate projects where recommending documentation practices from the get-go would be super-useful.

[Scott Miles]

For documentation, we have a system today that leverages YuiDoc tooling and a context-free documentation syntax. The output we consume is a JSON database, which can be rendered statically or on demand.

An example of some rendered documentation can be seen here: http://polymer.github.io/three-js/components/three-js/

The documentation renderer used is a component (polymer-doc-viewer) . The default landing page (which includes the docs) is generated by another component (polymer-home-page).

Yes, the actual database is for `webaudio-knob` while the page is supposed to be about `three-js`, that's just me being sloppy. I wasn't planning on sharing these materials exactly today, but since it came up ... =P

Now, this example is a bit half-baked for a couple of reasons: (1) we are evaluating other ways of generating docs, and (2) this is just a piece of the larger meta-environment needed to support a rich component ecosystem.

Our current thinking around this meta-system goes something like this (cribbed from some other notes I have):

Goals

• Decentralized (flexibility, decoupling, allow third-party innovation)

• Rich materials

• Low barrier to entry

• Free (support free server options)

• Easy to set up

Leverage

• Provide (optional) out-of-the-box solutions for docs, examples, sandboxing (moar components!)

• Use free GitHub services

Strawman: Requirements

To participate in the ecosystem a component should have

• github repository

• landing (aka home or index or information) page

• demo page

Component Identity

A component can be identified as a URL that points to a metadata file. The metadata (or the URL itself) identifies the github repository and the dispensation of the landing and demo pages.

No Cost Setup

Developer can set up live pages using GitHub servers by cloning the component repository into a gh-pages branch (and including dependencies; iow, clone working copy, bower install, push to gh-pages branch). This set up requires no customization and can be automated.

Example: three-js component installed to gh-pages:

landing page:

http://polymer.github.io/three-js/components/three-js/

demo page:

http://polymer.github.io/three-js/components/three-js/demo.html

(Links and content are variously messed up, these are just proof-of-concept mocks.)

Follow Polymer on Google+: plus.google.com/107187849809354688692
---
You received this message because you are subscribed to the Google Groups "Polymer" group.
To unsubscribe from this group and stop receiving emails from it, send an email to polymer-dev...@googlegroups.com.
To view this discussion on the web visit https://groups.google.com/d/msgid/polymer-dev/75b0e259-cd73-4806-b6ee-00cd7b1b7a17%40googlegroups.com.

[Addy Osmani]

Thanks for the walkthrough, Scott! I understand that much of this is proof-of-concept, but it's still highly useful. I'll take a look through your samples.

[Addy Osmani]

Hello Scott,

Just picking up on this thread once again :) We are currently evaluating how to prescribe best

practices around component documentation as part of WebComponents.org and a Polymer 

boilerplate project.

The current setup you have based on <polymer-doc-viewer> and <polymer-home-page> so far

work quite well, however I noticed that the source appears to rely on a self-hosted endpoint:

http://turbogadgetry.com/bowertopia/components/

If we were to model a way to auto-render docs using your setup today, would calling the above

endpoint be feasible or would you prefer for us to (1) wait until a more concrete docs approach has

been fleshed out or (2) a way to host this elsewhere (AppEngine?) so others can use it without

causing issues.

Cheers!

[Scott Miles]

Hi Addy,

My plan is for the core team is focus this week on tightening up our component set and fleshing out the docs and on-ramp materials. You're just a bit ahead of us. I hope to have clearer answers in a few days.

I'm leaning towards modifying our standard `index.html` to simply suggest you install `polymer-home-page` instead of redirecting you to an external site. WDYT?

Scott

To view this discussion on the web visit https://groups.google.com/d/msgid/polymer-dev/CAAKPnK8ce1bDtSZG0W0RWiQMiz5CfkdWuzmRKuwtzdNNsZE03Q%40mail.gmail.com.

[Eric Bidelman]

Being able to view live docs without having to install anything would be very nice.

What do we think about this:

webcomponents.org/docviewer?element=http://components-r-us.com/my-tag.html

/docviewer would contain <polymer-doc-viewer> and render the docs for my-tag.html (or whatever URL you pass it). Anyone that follows the documentation practices (CORs enable their imports, uses YUIDoc comments, etc) can use this.

Thoughts?

To view this discussion on the web visit https://groups.google.com/d/msgid/polymer-dev/CAHbmOLbND3RpoYW1wbH6d6UoqcVA_am1YP%2BDVS6q%3DRWD6bQaag%40mail.gmail.com.

[Addy Osmani]

I would absolutely <3 that. Being hosted on wc.org also makes it easier for us to encourage those writing elements with Brick/X-Tag/anything else to use the same docs strategy. 

[Eric Bidelman]

Scott, can <polymer-doc-viewer> be used for non-Polymer elements? Theoretically...if not practically? :)

[Scott Miles]

>> Scott, can <polymer-doc-viewer> be used for non-Polymer elements? Theoretically...if not practically? :)

Absolutely, this is always our goal. In my view, we vend 'web components' technology primarily, and actual elements only secondarily.

>> What do we think about this: webcomponents.org/docviewer?element=http://components-r-us.com/my-tag.html

I made a POC of this idea here: 

  http://polymer.github.io/polymer-doc-viewer

For example:

http://polymer.github.io/polymer-doc-viewer/?//polymer.github.io/google-map/components/google-map/google-map.html&//polymer.github.io/polymer-localstorage/components/polymer-localstorage/polymer-localstorage.htm

Scott

[Scott Miles]

Sorry, lost the last letter in the link. Fixed:

http://polymer.github.io/polymer-doc-viewer/?//polymer.github.io/google-map/components/google-map/google-map.html&//polymer.github.io/polymer-localstorage/components/polymer-localstorage/polymer-localstorage.html

[Addy Osmani]

That was quick! Thanks Scott.

Maybe once you guys have fleshed out the docs strategy we could figure where this should live long term? :) pp vs wc

[Benjamin Lupton]

Not sure if this has been covered yet, but it seems that the suggestion is to include documentation within my-component/my-component.html with the actual component definition. This seems strange to me as it would include the docs with the production component build. For us, we've been using my-component/index.html to include the documentation and a demo for a component. This seems like it could work really well, with perhaps a HTML comment inside my-component/my-component.html indicating for them to visit my-component/index.html for the docs.

Thoughts?

[Eric Bidelman]

There are a bunch of new developments in this area. We're currently fleshing out a common steup to document elements, provide a demo link, landing page, and a .zip download option other than Bower. It's still early, but here's an example if you're interested:

• Github source: https://github.com/polymer/core-ajax
• Landing page: http://polymer.github.io/core-ajax/
• Demo: http://polymer.github.io/core-ajax/components/core-ajax/demo.html
• Docs (component page): http://polymer.github.io/core-ajax/components/core-ajax/

You'll notice that the source on Github only has the bare essentials for the element. The component page use core-doc-viewer to parse the element file on the fly and render live documentation. Nothing is included with the element itself. The only requirement from authors is annotating their elements with JSdoc comments.

I realize this probably leaves you with a ton of questions :) We're hoping to document the workflow in the next week or two. Stay tuned!

Follow Polymer on Google+: plus.google.com/107187849809354688692

---
You received this message because you are subscribed to the Google Groups "Polymer" group.
To unsubscribe from this group and stop receiving emails from it, send an email to polymer-dev...@googlegroups.com.

To view this discussion on the web visit https://groups.google.com/d/msgid/polymer-dev/ea96c526-68f9-4ff6-acc1-a74b1cae18e1%40googlegroups.com.
For more options, visit https://groups.google.com/d/optout.

[Pascal Precht]

Hi Eric,

I wonder if this sort of automatic documentation is only made for polymer core (and ui) components, or if that should also be the way to go when implementing custom polymer elements.

Over at AngularJS, we've built a new tool to make automation of documentation generation called "dgeni". Basically the tool itself is nothing more than a system that consumes a stack of processors and pipes them at execution time. This gives us super high flexibility when it comes to custom features like custom annotations, custom templates, filters, actually what ever you want. It's still in early development but is already used for the angular docs.

Now I thought it'd probably also a cool thing to build a processor package for it that handles polymer specific features. Other people that develop polymer components could use the same features too then.

[Eric Bidelman]

On Mon, Apr 14, 2014 at 1:03 PM, Pascal Precht <pascal...@gmail.com> wrote:

Hi Eric,

I wonder if this sort of automatic documentation is only made for polymer core (and ui) components, or if that should also be the way to go when implementing custom polymer elements.

That's the idea. Any element created using Polymer can take advantage of this system. It requires very little effort from the author. You get a lot for free. Conceivably, the same tool could be adapted for vanilla custom elements, but we're starting small :)

Example I created using the tool (not part of Polymer's element set):

https://github.com/ebidel/geo-location

 

Over at AngularJS, we've built a new tool to make automation of documentation generation called "dgeni". Basically the tool itself is nothing more than a system that consumes a stack of processors and pipes them at execution time. This gives us super high flexibility when it comes to custom features like custom annotations, custom templates, filters, actually what ever you want. It's still in early development but is already used for the angular docs.

Now I thought it'd probably also a cool thing to build a processor package for it that handles polymer specific features. Other people that develop polymer components could use the same features too then.

On Monday, April 8, 2013 9:02:19 PM UTC+2, Eric Bidelman wrote:

Inspired by Mike K's great idea of self documenting custom elements, I've written a proposal to formalize the effort.

We have a great opportunity here to come up with best practices early on.

Proposal: Self Documenting Custom Elements

    - prototype - a custom element that uses this method.

    - it's <wc-documentation> (best viewed in Chrome Canary to get ::distributed()).

Things I like about this approach:

- The delivery mechanism is <link rel="import">. 

- Becomes the "view source of custom elements". Click an import's link -> get its docs.

- The docs themselves are custom elements

- works reasonably well in other modern browsers, especially if the toolkit polyfills are included.

Looking for everyone's feedback. 

Eric Bidelman

Follow Polymer on Google+: plus.google.com/107187849809354688692

---
You received this message because you are subscribed to the Google Groups "Polymer" group.
To unsubscribe from this group and stop receiving emails from it, send an email to polymer-dev...@googlegroups.com.

To view this discussion on the web visit https://groups.google.com/d/msgid/polymer-dev/f4d4b3d2-d9d3-41e8-a015-065851cc3bab%40googlegroups.com.

[Pascal Precht]

Alright, thanks!

[Jonathan Garbee]

My question with this is, why restrict repositories just to github? There are other hosting repositories out there that people and companies use (Let's just completely overlook the fact that GH is the biggest and most likely won't be going away anytime soon.) Unless there is something specific tied to github then it could be best named as "repo" or "repository" as compared to a github attribute.

-Garbee