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

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

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.