Documentation Not working for Polymer 2.0 / Native Web Components

[kevinpschaaf]

From @gaurav21r on November 1, 2016 17:40

According to https://youtu.be/guYHn0P8bKQ?list=PLNYkxOF6rcICc687SxHQRuo9TVNOJelSZ&t=631 The Polymer Analyzer now understands Native Web Components, Polymer 1.0 and Polymer 2.0! :open_mouth: :smile: :+1:

However when I tried to document using the usual Comment convention (albeit in JSDoc style as given here https://www.polymer-project.org/1.0/docs/tools/documentation#element-summaries) for my native WebComponent MyElement extends HTMLElement, the <iron-component-page> rendered a No documentation found.

Copied from original issue: Polymer/polymer#4121

[kevinpschaaf]

From @justinfagnani on November 7, 2016 18:42

<iron-component-page> does not yet use the new Analyzer. The new tools are pre-release and not integrated into everything yet.

[kevinpschaaf]

From @gaurav21r on November 8, 2016 5:58

@justinfagnani Is there a branch in <iron-component-page> where the new Analyzer is being integrated? We may be able to contribute / give feedback on its working since we've worked with the Analyzer and have a few native components we want to see the documentation for.

[kevinpschaaf]

From @justinfagnani on November 18, 2016 20:35

@gaurav21r no, no one's working on iron-component-page just yet. One difference going forward is that we don't intend to run the Analyzer in-browser for documentation, but to base documentation on the Analyzer's JSON output.

[gaurav21r]

Any updates on this? @kevinpschaaf @justinfagnani ?

[marybeshaw]

I am interested in finding out progress on this as well. Polymer 2.0 has a release candidate out... are demos and documentation using iron-component-page not considered part of essential Polymer functionality?

[justinfagnani]

@marybeshaw and @gaurav21r we had to do some less-than-final changes to iron-doc-viewer to produce the docs for Polymer 2. We'll be cleaning those up over the next few weeks before we release final versions of core and the elements.

FYI, the RC release was just of Polymer core. The elements are not technically RC yet, though they're close.

iron-component-page itself, might or might not get ported to 2.0 Since we're not running analysis in the browser anymore, iron-doc-viewer and its new related elements like iron-doc-element and iron-doc-mixin can directly process the JSON output of the Analyzer.

To track progress on the new elements, see the 2.0-analyzer branch: https://github.com/PolymerElements/iron-doc-viewer/tree/2.0-analyzer

[aomarks]

The current plan is to update iron-component-page to work with the new Analyzer output, but by reading a JSON file instead of doing analysis in the browser, as mentioned above. We'll also automate analysis and docs serving via polymer serve.

[AVGP]

@aomarks Is there any documentation on how to get the new Analyzer to produce the output that <iron-component-page> consumes? When I run .analyse() I get something that isn't JSON-serializable...

I'm also happy to hear "Please write a script that produces this output", happy to do so - but I'm confused right now ^^"

[aomarks]

@AVGP you want to pass that analyzer result object to generateAnalysis (also from the polymer-analyzer package) to get a JSON serializable format. Note that polymer analyze > analysis.json from the command line will also do this.

But also, big caveat that <iron-component-page> currently does not understand the output of the new Polymer analyzer, it only supports our legacy hydrolysis analyzer output, and hydrolysis does not understand Polymer 2.0 components very well.

Expect an update to address this in the next couple of weeks, I'll make sure to ping this issue.

[AVGP]

@aomarks Thanks for the clarification - is there anyone I can talk to help implement it? I'm happy to contribute :)

[aomarks]

Hi all. We've got a new iron-component-page almost ready to go. You can check out a live demo at https://aomarks-test-docs.appspot.com/ or checkout the master branch or a 3.0.0-rc release to play with it early. The new README describes the changes and how to use it. Feedback welcome!

[JohnRiv]

Good to hear! I just tried updating one of our Polymer 2.0 components to the latest on master and gave the README instructions a try. When I load http://localhost:8080/, I'm not seeing any output. The toast message says Could not load descriptor "". No errors in the console. I did notice that I don't see any references to analysis.json in the Network tab of DevTools. Any suggestions on where to start looking to debug it? The analysis.json does exist.

[aomarks]

@JohnRiv check out the very latest changes on master or 3.0.0-rc.2 -- should help.

[JohnRiv]

Sweet! Just pulled those changes down and it works. Thanks @aomarks, very excited to start using this!

[aomarks]

See also https://github.com/PolymerElements/iron-component-page/issues/132 for some of the open issues I'm currently working on.

[aomarks]

For anyone following along, I just published an RC5 with demos showing in the nav, and a bunch of style updates. Getting close to 3.0 release, hopefully.

Polymer docs: https://aomarks-test-docs.appspot.com/#/elements/Polymer.Element app-layout: https://aomarks-test-docs.appspot.com/app-layout.html#/elements/app-box

[aomarks]

Just published 3.0.0 so closing this issue!

Info at https://github.com/PolymerElements/iron-component-page

[limonte]

Awesome! Thanks a lot @aomarks!

PS. There's a room for improvement for release notes of the major release ;)

[marybeshaw]

Just a note - it would be good to update the Polymer 2 documentation to reflect this: https://www.polymer-project.org/2.0/docs/tools/documentation

[aomarks]

@marybeshaw Yeah, that will get updated soon. https://github.com/Polymer/docs/issues/2210