Polymer Logo Home Guides Feature overview Try Polymer Install Polymer 3.x Tutorial: Build an element 1. Get set up 2. Add shadow DOM 3. Data binding & properties 4. React to input 5. Theming with custom properties About this release What's new in 3.0 Upgrade guide Release notes Custom elements Custom element concepts Define an element Declare properties Working with legacy elements Shadow DOM & styling Shadow DOM concepts DOM templating Style shadow DOM Custom CSS properties Events Handle and fire events Gesture events Data system Data system concepts Work with object and array data Observers and computed properties Data binding Helper elements Browser support Overview Polyfills ES6 and modules Tools Tools overview Polymer CLI CLI commands Create an element project Create an application project Document your elements Test your elements polymer.json specification Node support Build apps Overview App templates Build for production Serve your app The PRPL pattern Service worker Reference Glossary Global settings API Reference index polymer-element.js Elements array-selector.js custom-style.js dom-bind.js dom-if.js dom-module.js dom-repeat.js Mixins dir-mixin.js disable-upgrade-mixin.js element-mixin.js gesture-event-listeners.js mutable-data.js properties-changed.js properties-mixin.js property-accessors.js property-effects.js strict-binding-parser.js template-stamp.js Utils array-splice.js async.js case-map.js debounce.js flattened-nodes-observer.js flush.js gestures.js html-tag.js mixin.js path.js render-status.js resolve-url.js settings.js style-gather.js telemetry.js templatize.js Legacy class.js legacy-data-mixin.js legacy-element-mixin.js mutable-data-behavior.js polymer-fn.js polymer.dom.js templatizer-behavior.js

The Polymer library is in maintenance mode. For new development, we recommend Lit.

Contents

You can provide API docs for Polymer custom elements by writing documentation comments in your source files. Using the iron-component-pages element, you can create a simple documentation page for your elements that displays your comments rendered as API documentation.

See a template example on GitHub.

Create a documentation page for your project

To create a documentation page for your project:

  1. Install Polymer CLI. Polymer CLI gives you a command-line interface to Polymer Analyzer (among other things).

  2. cd to your project directory. This can be a custom element, a full app, or even a plain JavaScript library. Polymer Analyzer will discover all of the interesting items recursively in your project directory.

  3. Analyze your project with polymer analyze > analysis.json. A JSON descriptor file is produced. By default iron-component-page will look for a file called analysis.json (you can override this with the descriptor-url property).

  4. Add iron-component-page as a dev dependency of your project with the following command: npm install @polymer/iron-component-page@next --save-dev.

  5. Create an HTML file to instantiate an iron-component-page element (e.g. index.html or docs.html). Note that you may need to adjust your import paths depending on your project layout.

     <!doctype html>
 <html>
   <head>
     <meta charset="utf-8">
     <meta name="viewport" content="width=device-width, minimum-scale=1.0, initial-scale=1.0, user-scalable=yes">
     <script src="/node_modules/@webcomponents/webcomponentsjs/webcomponents-bundle.js"></script>
     <script type="module" src="/node_modules/@polymer/iron-component-page/iron-component-page.js"></script>
   </head>
   <body>
     <iron-component-page></iron-component-page>
   </body>
 </html>

Serve the page using any local web server, such as polymer serve or python -m SimpleHTTPServer.

You can use Polymer CLI's polymer serve command to preview element docs while you're developing a component.

To preview element docs:

  1. Run polymer serve.

  2. Open the element's top-level index.html in a browser:

    localhost:8080/components/my-el/

    Where my-el is the name of your element.

If everything is set up right, you should see a documentation page for your element, even if you haven't written any doc comments yet.

If you have multiple elements or behaviors, use the pulldown menu in the top-left corner to choose a documentation page.

Add API docs to your elements by adding inline JavaScript comments.

Provide a thorough overview of what the element does, and provide examples of common usage patterns. Format the documentation as markdown.

Denote your element summary by inserting a JavaScript comment directly preceding your class definition. You can use Markdown headings to break up long element summaries.

  /**
   * `<awesome-sauce>` injects a healthy dose of awesome into your page.
   * ## This is an h2 heading
   * In typical use, just slap some `<awesome-sauce>` at the top of your body:
   * <body>
   *   <awesome-sauce></awesome-sauce>
   * Wham! It's all awesome now!
   * @customElement
   * @polymer
   * @demo https://path/to/awesomeness/demo/
   *
   */
  class AwesomeSauce extends Polymer.Element {
    ...
  }

Polymer custom elements should include the @customElement and @polymer tags.

The first tag encountered in the comment block marks the end of the element summary. Any line starting with an at-sign (@) is interpreted as a tag. Any remaining non-tag comments in the comment block are ignored.

Document all public properties. Docs should start with a one line summary. Make sure that the property's type is annotated.

Denote your property documentation with a JavaScript comment preceding the property declaration. The simplest property documentation can be a single line:

/** Whether this element is currently awesome. */
isAwesome: Boolean,

If the property doesn't specify a type, or that type is not primitive, be sure to annotate the type properly:

/**
 * Metadata describing what has been made awesome on the page.
 *
 * @type {{elements: Array<HTMLElement>, level: number}}
 */
sauce: Object,

Private properties should be prefixed with an underscore (_):

/** An awesome message */
_message: String,

Follow the property guidelines. Additionally, make sure the types for all params and return values are documented.

For example:

/**
 * Applies awesomeness to `element`.
 *
 * @param {HTMLElement} element The element to be made awesome.
 * @param {number} level The numeric level of awesomeness. A value
 *     between `1` and `11`.
 * @param {Array<HTMLElements>=} refs Optional referenced elements
 *     that become awesome by proxy.
 * @return {number} The cumulative level of awesomeness.
 */
makeAwesome: function makeAwesome(element, level, refs) {

Events must be annotated explicitly with an @event tag.

Event properties are documented with the @param tag, just like method parameters.

For example:

/**
 * Fired when `element` changes its awesomeness level.
 *
 * @event awesome-change
 * @param {number} newAwesome New level of awesomeness.
 */

Like an element, but add @mixinFunction and possibly @mixinClass.

Include a mixin summary immediately before the mixin function declaration. The summary is like an element summary, but must include the @polymer and @mixinFunction tags.

Document any properties, methods or events inside the mixin just like you would for an element.

For more information on mixins, see Sharing code with class expression mixins in Custom element concepts.

/*
 * This mixin lets you travel faster than light speed, almost.
 * @polymer
 * @mixinFunction
 *
MyNamespace.WarpSpeedMixin = (superclass) => class extends superclass {
  ...
}

If your mixin function doesn't immediately return the class, as above, you may need to add the @mixinClass tag immediately before the class declaration. For example:

/*
 * This mixin does something really complicated.
 * @polymer
 * @mixinFunction
 *
MyNamespace.ReallyComplicatedMixin = Polymer.dedupingMixin((superclass) =>

   // do some other stuff before creating the class...
   ...

  /*
   * @polymer
   * @mixinClass
   */
  class mixin extends superclass {
    ...
  }

  // finally, return the mixin class
  return mixin;
);

An element that applies a mixin should add the @appliesMixin tag:

/*
 * An element with a mixin
 * @polymer
 * @customElement
 * @appliesMixin MyNamespace.WarpSpeedMixin
class MyMixedUpElement extends MyNamespace.WarpSpeedMixin(Polymer.Element) { ... }

If a mixin applies one or more mixins, it should also include the @appliesMixin tag.

Like an element, but add @polymerBehavior.

Include a behavior summary, just like an element summary, but ending with a @polymerBehavior tag. The behavior name can be specified explicitly if the doc parser can't infer it correctly.

@polymerBehavior MyOddBehavior

Document methods, properties, etc. just like an element.

For example:

/**
 * Behavior that highlights stuff.
 *
 * @polymerBehavior
 */
MyBehaviors.HighlightStuff = { ... }

When extending a behavior, you place the new functionality in an implementation object as described in Extending behaviors.

The implementation object must be named with the behavior name followed by Impl, and it must be annotated with @polymerBehavior followed by the real behavior name:

/**
 * Extended behavior.
 *
 * @polymerBehavior SuperBehavior
 */
MyBehaviors.SuperBehaviorImpl = { ... }

The actual behavior is simply an array of behaviors, ending with the implementation object. It must also be annotated with @polymerBehavior:

/**
 * @polymerBehavior
 */
MyBehaviors.SuperBehavior =
    [MyBehaviors.BaseBehavior, MyBehaviors.SuperBehaviorImpl]

The documentation system merges these declarations into a single behavior (in this case, MyBehaviors.SuperBehavior).

Currently there is no tag for custom CSS properties and mixins. Document properties and mixins in a table in the main element description:

### 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 | `{}`

Adhere to Closure-compatible type expressions.

<iron-component-page> supports the following JSDoc tags:

  • @appliesMixin
  • @customElement
  • @demo
  • @event
  • @mixinClass
  • @mixinFunction
  • @polymer
  • @polymerBehavior
  • @type

When in doubt, keep to the 3rd person present tense and keep it simple.

A few guidelines for consistency:

  • Use the 3rd person for descriptions.

    • Good. "Creates a foo."
    • Avoid. "Create a foo."

    Use 2nd person ("Do this...") when you're trying to be prescriptive, such as, "Add the toolbar attribute to the element you want to use as a toolbar."

  • Use the present tense whenever possible.

    • Good. "Clicking the element starts an animation."
    • Avoid. "Clicking the element will start an animation."

  • Start method descriptions with an active verb.

    • Good. "Starts the animation."
    • Avoid. "This method starts the animation."

  • It's OK to use a fragment, especially in a short description.

    • Good. "Item height, in pixels."
    • Avoid. "This property specifies the item height, in pixels."

    (Fragments should still start with a capital letter and have ending punctuation.)

The JavaDoc Style Guide is a good resource on general API doc style. Most of the style rules described there can be applied here as well.