Double hyphens are invalid HTML comments

[shannonmoeller]

Double hyphens are disallowed in HTML/XML comments. Therefore, the recommended format for documenting element styles is invalid markup:

<!--

...

### Styling

`<paper-button>` provides the following custom properties and mixins
for styling:

Custom property | Description | Default
----------------|-------------|----------
`--paper-button-ink-color` | Background color of the ripple | Based on the button's color
`--paper-button` | Mixin applied to the button | `{}`

...

-->

Expected outcome

There should be a way of documenting dom-module styles using valid code.

Actual outcome

It's possible to move the documentation into the <script> tag and use c-style comments, with one catch: the inability to namespace element definitions. Doing so breaks the comment association in Hydrolysis.

Personal Ideal Change

The ability to document element styles in c-style comments within the element's <style> and <script> tags. This way developers have a choice of putting all of the element documentation into the <script> tag or to break up the documentation into the flow of the code where the HTML documentation is in the HTML, style documentation in the CSS, and API documentation in the JS.

One possible solution would be to support a @polymerElement tag similar to the @polymerBehavior tag.

[shannonmoeller]

I haven't tested to see whether the namespacing issue has been resolved in polymer-analyzer.