Prepare release of iron-component-page 3.0.0

[aomarks]

When this PR is merged, I'll tag the final 3.0.0 release of iron-component-page and iron-doc-viewer. If there are any issues or questions that should block the release, let's discuss here.

See the summary of changes at the bottom of the README.

Live demos:

• Polymer 2 core: https://aomarks-test-docs.appspot.com
• app-layout: https://aomarks-test-docs.appspot.com/app-layout.html

[samuelli]

Thought on merging <iron-component-page> into the iron-doc-viewer repo?

• I've seen a bunch of PRs on both sides since they're tightly coupled
• Those upgrading will already have to manually update to iron-component-page 3.x. Merging will mean they have to point to iron-doc-viewer 3.x.

[justinfagnani]

I'm personally reluctant to do repo refactorings at this point.

[justinfagnani]

@arthurevans this would need to be updated: https://www.polymer-project.org/2.0/docs/tools/documentation

[aomarks]

@arthurevans There's a little tutorial in the new README about how to use the new iron-component-page, since it doesn't run automatically in the browser like the Hydrolysis version did: https://github.com/PolymerElements/iron-component-page#documenting-your-element

I also filed https://github.com/Polymer/polyserve/issues/202 to track adding some magic to polyserve to smooth this over.

[jsilvermist]

@samuelli I feel like merging these repo's makes a lot of sense, there's not really any point in separating them at this point except for legacy continuity, and what better time for a change than with 3.0!

[arthurevans]

Nice. Works like a charm.

Created https://github.com/Polymer/docs/issues/2210 for the related docs update. I believe @katejeffreys will be handling this.

We'll also need an updated list of JSDOC tags supported by the new analyzer/iron-doc-viewer. I think that exists in a PR somewhere ...?

[justinfagnani]

@arthurevans Since you filed the docs issue, and aside from jsdoc tags, would this be ready to be approved, or is our intention to wait until docs are ready?

The current jsdoc tags were added here: https://github.com/Polymer/polymer-analyzer/pull/641 edit: this was the jsdoc tag issue with more detail: https://github.com/Polymer/polymer-analyzer/issues/605

[arthurevans]

It's good by me. This doesn't break anything that works now, so perfectly OK for docs to trail behind implementation here.

[arthurevans]

Heh. I was going to put in a feature request to flip the order of method descriptions & parameters, then I checked the latest version and realized you'd already done that. Double approved!

[aomarks]

On the renaming. I do think it would sense conceptually for this element to be called iron-doc-page, especially as it has evolved into a fairly general purpose documentation viewer. It would also help with development, since as Sam mentioned the two are pretty tightly coupled, and we often end up with paired PRs and version bumps.

The downsides are:

• More install (though not runtime) dependencies. iron-doc-viewer would gain install dependencies of app-layout, iron-ajax, iron-icons, paper-icon-button, and paper-toast.
• All of the existing index.html files that people have in their repos (including all of the Polymer catalog) would need to be updated. (Although we could turn this element into a pure delegating wrapper, but that feels a bit gross). As it stands, users would only need to update their bower deps and run polymer analyze for things to just work, and if we add the polyserve magic I mentioned above, some users wouldn't have to do anything at all.

So I think I'm leaning towards not renaming.

[justinfagnani]

+1 to not renaming now. There's been a little talk of a new "meta" elements set (elements related to developing elements, possibly including test-fixture), so we should wait and figure that out.