more API docs

polymer-meta.html

@@ -8,10 +8,35 @@
  * @module Polymer Elements
  */
 /**
- * polymer-meta is used to manage metadata.  When an instance of polymer-meta
- * is created, it's automatically registered and add to the metaData storage given an id
- * is set on the element. Use byId() to retrive a specific polymer-meta and
- * the property "list" to retrieve all registered polymer-meta's.
+ * The `polymer-meta` elements provides a method of constructing a 
+ * self-organizing database.  It is useful to collate element meta-data for 
+ * things like catalogs and for sandbox.
+ *
+ * Example, an element folder has a `metadata.html` file in it, that contains a 
+ * polymer-meta, something like this:
+ *
+ *     <polymer-meta id="my-element">
+ *       <property name="color" type="color"></property>
+ *     </polymer-meta>
+ *
+ * An application can import as many of these files as it wants, and then use 
+ * polymer-meta again to access the collected data.
+ *
+ *     <script>
+ *       var meta = document.createElement('polymer-meta');
+ *       console.log(meta.list); // dump a list of all meta-data elements that have been created
+ *     </script>
+ *
+ * Use `byId(id)` to retrive a specific polymer-meta.
+ *
+ *     <script>
+ *       var meta = document.createElement('polymer-meta');
+ *       console.log(meta.byId('my-element'));
+ *     </script>
+ *
+ * By default all meta-data are stored in a signle databse.  If your meta-data 
+ * have different types and want them to be stored separately, use `type` to 
+ * differentiate them.
  *
  * @class polymer-meta
  */
@@ -26,6 +51,14 @@
 
       Polymer('polymer-meta', {
         alwaysPrepare: true,
+        /**
+         * The type of meta-data.  All meta-data with the same type with be
+         * stored together.
+         * 
+         * @attribute type
+         * @type string
+         * @default 'default'
+         */
         type: 'default',
         ready: function() {
           this.idChanged();
@@ -58,12 +91,44 @@
             this.metaArray.splice(i, 1);
           }
         },
+        /**
+         * Returns a list of all meta-data elements with the same type.
+         * 
+         * @attribute list
+         * @type array
+         * @default []
+         */
         get list() {
           return this.metaArray;
         },
+        /**
+         * Returns the first `<template>` in the `<polymer-meta>` subtree. This
+         * is useful to store element example.
+         *
+         *     <polymer-meta id="polymer-ui-toolbar" label="Polymer Toolbar">
+         *       <template>
+         *         <polymer-ui-toolbar theme="polymer-ui-light-theme">
+         *           <polymer-ui-icon-button icon="menu"></polymer-ui-icon-button>
+         *           <div flex>Title</div>
+         *           <polymer-ui-icon-button icon="add"></polymer-ui-icon-button>
+         *         </polymer-ui-toolbar>
+         *       </template>
+         *     </polymer-meta>
+         * 
+         * @attribute archetype
+         * @type node
+         * @default null
+         */
         get archetype() {
           return this.querySelector('template');
         },
+        /**
+         * Retrieves meta-data by ID.
+         *
+         * @method byId
+         * @param {String} id The ID of the meta-data to be returned.
+         * @returns Returns meta-data.
+         */
         byId: function(id) {
           return this.metaData[id];
         },