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.
Double hyphens are disallowed in HTML/XML comments. Therefore, the recommended format for documenting element styles is invalid markup:
Expected outcome
There should be a way of documenting
dom-modulestyles 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
@polymerElementtag similar to the@polymerBehaviortag.