Settings Rewrite: Update comments on related to routing.

chrome/browser/resources/settings/settings_page/settings_animated_pages.js

 // Copyright 2015 The Chromium Authors. All rights reserved.
 // Use of this source code is governed by a BSD-style license that can be
 // found in the LICENSE file.
 
 /**
  * @fileoverview
  * 'settings-animated-pages' is a container for a page and animated subpages.
  * It provides a set of common behaviors and animations.
  *
+ * The section name must match the name specified in settings_router.js.
+ * Otherwise, settings-animated-pages will not transition between subpages.
+ *
  * Example:
  *
  *    <settings-animated-pages current-route="{{currentRoute}}"
-          route-root="advanced/privacy" redirect-root-route-to="advanced">
+ *        section="privacy">
  *      <!-- Insert your section controls here -->
  *    </settings-animated-pages>
  *
  * @group Chrome Settings Elements
  * @element settings-animated-pages
  */
 Polymer({
   is: 'settings-animated-pages',
 
   properties: {
     /**
      * Contains the current route.
      */
     currentRoute: {
       type: Object,
       notify: true,
       observer: 'currentRouteChanged_',
     },
 
     /**
      * Routes with this section activate this element. For instance, if this
      * property is 'search', and currentRoute.section is also set to 'search',
      * this element will display the subpage in currentRoute.subpage.
      */

[michaelpg, 2015/12/10 00:23:44]

Could you consider adding the comment here instead? I usually look to these
comments to determine what a property does/how to use it.

[tommycli, 2015/12/10 01:59:51]

Done.

     section: {
       type: String,
     },
   },
 
   /** @override */
   created: function() {
     this.addEventListener('subpage-back', function() {
       assert(this.currentRoute.section == this.section);
       assert(this.currentRoute.subpage.length >= 1);
@@ skipping 35 matching lines @@
    * Buttons in this pageset should use this method to transition to subpages.
    */
   setSubpageChain: function(subpage) {
     this.currentRoute = {
       page: this.currentRoute.page,
       section: subpage.length > 0 ? this.section : '',
       subpage: subpage,
     };
   },
 });