CODEWITHSUNDEEP
polymer
lazieburd
lazieburd

Reputation: 2786

Anyone develop any tools for generating documentation for elements?

Kinda like javadocs but for polymer-elements.

I get the feeling these were generated from a tool http://www.polymer-project.org/docs/elements/polymer-elements.html http://www.polymer-project.org/docs/elements/polymer-ui-elements.html

If no tools you can share specifically, maybe someone can share description of approach. XSLT?

Upvotes: 3

Views: 779

Answers (2)

Scott Miles
Scott Miles

Reputation: 11027

We are in the process of cleaning these things up and documenting the documentation tools just in the next couple of weeks. I'm sorry that it's all a bit rough around the edges today. Having said that, here is some info:

Polymer vends a polymer-doc-viewer component that you can point to (one or more) HTML files to generate documentation from source comments. Look at the demo.html to see some possible usage.

We also have polymer-docs component which will render docs for all polymer elements that it knows about that you have installed. Here is a live version installed at gh-pages:

http://polymer.github.io/polymer-docs/components/polymer-docs/

The comment format is JSDoc-like, mostly copied from YUIDoc. The rendered output will probably get a face-lift soon, but this is one of the good parts: if we change it and then you update your copy of component, it will just work.

You can also customize or make your own polymer-doc-viewer, as the code is pretty simple. There is another component (included) called context-free-parser that actually snarfs up the documentation data into a JavaScript object (data model) so you can render it anyway you like.

Upvotes: 3

Matt2012
Matt2012

Reputation: 130

There was a proposal for self documenting elements.

https://docs.google.com/document/d/15erfuJ9kGTTFZIxM1E8mKSdvZmb9RPr2BwMQvU48PVI

some examples were given

<wc-documentation name="my-tag">
  <summary>My tag is the bees knees.</summary>
</wc-documentation>
<wc-documentation name="my-tag" version="0.0.1"
                  github="https://github.com/Polymer/polymer"
                  home="http://polymer-project.org">
  <summary>...</summary>
  <pre class="example">...</pre>
</wc-documentation>
<wc-documentation name="my-tag">
  <div class="api">
    <p>This element supports the following methods:</p>
    <dl public>
      <dt>foo()</dt>
      <dd>Awesome method.</dd>
    </dl>
    <dl private>
      <dt>bar_()</dt>
      <dd>Privacy is key.</dd>
    </dl>
  </div>
</wc-documentation>

Discussion here

https://groups.google.com/forum/#!searchin/polymer-dev/documentation/polymer-dev/NFQ4hIgZSo4/bBVvMD6_jMEJ

There was some concern to the amount of unessesary boiler plate within the elements. This finally led to a prototype for a document viewer element

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

Upvotes: 0

Related Questions