在Polymer 1.0中记录库/混合/行为元素

Question

I had a Polymer 0.5 element that I mainly used as a library which I injected into other elements using mixins. I formatted it as followed and all of the JSDoc notation showed up in index.html :

<polymer-element name="easy-search-lib" attributes="">

  <template>

    <content></content>

  </template>

  <script>

    var EasySearch = {

      /**
       * Returns whether the given domain matches search.
       *
       * @method matches
       * @param {String} query String being searched for.
       * @param {String} text Text being searched within.
       * @return {Boolean} Returns if there is a match.
       */
      matches: function(query, text){
        query = this.getQuery(query);
        return query.test(text);
      }

      //...

    };

    Polymer(Polymer.mixin({

      /**
       * Convenience function for testing, binds EasySearch to Polymer element.
       *
       * @attribute EasySearch
       * @type object
       */
      EasySearch: EasySearch

    }, EasySearch));

  </script>

</polymer-element>

Polymer 1.0 replaced mixins with behaviors and gives the following example:

<script>
    HighlightBehavior = {

      properties: {
        isHighlighted: {
          type: Boolean,
          value: false,
          notify: true,
          observer: '_highlightChanged'
        }
      },

      listeners: {
        click: '_toggleHighlight'
      },

      created: function() {
        console.log('Highlighting for ', this, + 'enabled!');
      },

      _toggleHighlight: function() {
        this.isHighlighted = !this.isHighlighted;
      },

      _highlightChanged: function(value) {
        this.toggleClass('highlighted', value);
      }

    };
</script>

Note that there is no <dom-module id="highlight-behavior"> nor Polymer({...}) element declaration.

I followed this example exactly, but nothing showed up when I visited index.html. So I tried emulating what I had done for 0.5:

<script>

  var EasySearchLib = {

    EasySearch : {

      /**
       * Returns whether the given domain matches search.
       *
       * @method matches
       * @param {String} query String being searched for.
       * @param {String} text Text being searched within.
       * @return {Boolean} Returns if there is a match.
       */
      matches: function(query, text){
        query = this.getQuery(query);
        return query.test(text);
      }

      //...
     }
  };

  Polymer({

    is: 'easy-search-lib',

    properties: {

      /**
       * `fancy` indicates that the element should don a monocle and tophat,
       * while checking its pocket watch.
       */
      EasySearchLib: EasySearchLib
    }

  });

</script>

I also tried declaring variations of the attribute assignment ( EasySearch: EasySearchLib.EasySearch ) and throwing in a behaviors: [EasySearchLib] but nothing shows up in the documentation.

What's the best way of getting documentation for behaviors/libraries to show up when visiting index.html?

Answer 1

Put this before your behavior object definition:

/** @polymerBehavior */
var MyBehavior = {};

If you are putting multiple behaviors in one object, you will probably want to use this:

var EasySearchLib = {

  /** @polymerBehavior EasySearchLib.EasySearch */
  EasySearch: {}
}

Alternatively, I am in a similar situation where I define my namespace object beforehand with:

var EasySearchLib = EasySearchLib || {};

At the head of the document, then define the behavior with:

/** @polymerBehavior */
EasySearchLib.EasySearch = {};

This lets the parser infer the name of the behavior pretty easily. It also allows you to split the individual behaviors into separate files and attach them in any order.

Additional documentation: http://polymerelements.github.io/style-guide/#behaviors