Activity templates cleanup.

This change cleans up the BlankActivity and MasterDetailFlow activity templates
in the following ways:

- Unused search icons are removed.
- Many comments are added for a better explanation of what's going on. See
  http://code.google.com/p/android/issues/detail?id=34463
- Code and comments are in better alignment with Android code style and
  import order (per http://source.android.com/source/code-style.html)
- Non-trivial BlankActivity templates now require API 11 instead of 14.
  More work TBD here.
- Templates are more lint-friendly.
- android:parentActivityName is added when building against API 16.

Change-Id: Iba7b807c7567b161b0e50fb39306209172627c35

31 files changed, 400 insertions, 191 deletions

diff --git a/templates/activities/BlankActivity/recipe.xml.ftl b/templates/activities/BlankActivity/recipe.xml.ftl
index 05c5d57..8ed9f51 100644
--- a/templates/activities/BlankActivity/recipe.xml.ftl
+++ b/templates/activities/BlankActivity/recipe.xml.ftl
@@ -2,10 +2,6 @@
 <recipe>
     <merge from="AndroidManifest.xml.ftl" />
 
-    <copy from="res/drawable-hdpi" />
-    <copy from="res/drawable-mdpi" />
-    <copy from="res/drawable-xhdpi" />
-
     <instantiate from="res/menu/main.xml.ftl"
             to="res/menu/${menuName}.xml" />
 
diff --git a/templates/activities/BlankActivity/root/AndroidManifest.xml.ftl b/templates/activities/BlankActivity/root/AndroidManifest.xml.ftl
index ec20836..30da501 100644
--- a/templates/activities/BlankActivity/root/AndroidManifest.xml.ftl
+++ b/templates/activities/BlankActivity/root/AndroidManifest.xml.ftl
@@ -2,7 +2,8 @@
 
     <application>
         <activity android:name=".${activityClass}"
-            android:label="@string/title_${activityToLayout(activityClass)}">
+            android:label="@string/title_${activityToLayout(activityClass)}"
+            <#if buildApi gte 16 && parentActivityClass != "">android:parentActivityName="${parentActivityClass}"</#if>>
             <#if parentActivityClass != "">
             <meta-data android:name="android.support.PARENT_ACTIVITY"
                 android:value="${parentActivityClass}" />
diff --git a/templates/activities/BlankActivity/root/res/drawable-hdpi/ic_action_search.png b/templates/activities/BlankActivity/root/res/drawable-hdpi/ic_action_search.png
deleted file mode 100644
index 67de12d..0000000
--- a/templates/activities/BlankActivity/root/res/drawable-hdpi/ic_action_search.png
+++ /dev/null
diff --git a/templates/activities/BlankActivity/root/res/drawable-mdpi/ic_action_search.png b/templates/activities/BlankActivity/root/res/drawable-mdpi/ic_action_search.png
deleted file mode 100644
index 134d549..0000000
--- a/templates/activities/BlankActivity/root/res/drawable-mdpi/ic_action_search.png
+++ /dev/null
diff --git a/templates/activities/BlankActivity/root/res/drawable-xhdpi/ic_action_search.png b/templates/activities/BlankActivity/root/res/drawable-xhdpi/ic_action_search.png
deleted file mode 100644
index d699c6b..0000000
--- a/templates/activities/BlankActivity/root/res/drawable-xhdpi/ic_action_search.png
+++ /dev/null
diff --git a/templates/activities/BlankActivity/root/res/layout/activity_fragment_container.xml b/templates/activities/BlankActivity/root/res/layout/activity_fragment_container.xml
index 3128b5f..935d379 100644
--- a/templates/activities/BlankActivity/root/res/layout/activity_fragment_container.xml
+++ b/templates/activities/BlankActivity/root/res/layout/activity_fragment_container.xml
@@ -3,4 +3,5 @@
     android:id="@+id/container"
     android:layout_width="match_parent"
     android:layout_height="match_parent"
-    tools:context=".${activityClass}" />
+    tools:context=".${activityClass}"
+    tools:ignore="MergeRootFrame" />
diff --git a/templates/activities/BlankActivity/root/res/layout/activity_pager.xml.ftl b/templates/activities/BlankActivity/root/res/layout/activity_pager.xml.ftl
index c8f1604..ab57463 100644
--- a/templates/activities/BlankActivity/root/res/layout/activity_pager.xml.ftl
+++ b/templates/activities/BlankActivity/root/res/layout/activity_pager.xml.ftl
@@ -9,14 +9,16 @@
     This title strip will display the currently visible page title, as well as the page
     titles for adjacent pages.
     -->
-    <android.support.v4.view.PagerTitleStrip android:id="@+id/pager_title_strip"
+
+    <android.support.v4.view.PagerTitleStrip
+        android:id="@+id/pager_title_strip"
         android:layout_width="match_parent"
         android:layout_height="wrap_content"
         android:layout_gravity="top"
         android:background="#33b5e5"
-        android:textColor="#fff"
+        android:paddingBottom="4dp"
         android:paddingTop="4dp"
-        android:paddingBottom="4dp" />
+        android:textColor="#fff" />
 
 </android.support.v4.view.ViewPager>
 </#if>
diff --git a/templates/activities/BlankActivity/root/src/app_package/DropdownActivity.java.ftl b/templates/activities/BlankActivity/root/src/app_package/DropdownActivity.java.ftl
index a7bbff0..fb19202 100644
--- a/templates/activities/BlankActivity/root/src/app_package/DropdownActivity.java.ftl
+++ b/templates/activities/BlankActivity/root/src/app_package/DropdownActivity.java.ftl
@@ -1,12 +1,12 @@
 package ${packageName};
 
+<#if minApi < 14>import android.annotation.TargetApi;</#if>
 import android.app.ActionBar;
-import android.app.FragmentTransaction;
-import android.content.Context;
 import android.os.Bundle;
+<#if minApi < 14>import android.content.Context;
+import android.os.Build;</#if>
 import android.support.v4.app.Fragment;
 import android.support.v4.app.FragmentActivity;
-import android.support.v4.app.FragmentManager;
 import android.support.v4.app.NavUtils;
 import android.view.Gravity;
 import android.view.LayoutInflater;
@@ -19,29 +19,34 @@ import android.widget.TextView;
 
 public class ${activityClass} extends FragmentActivity implements ActionBar.OnNavigationListener {
 
+    /**
+     * The serialization (saved instance state) Bundle key representing the
+     * current dropdown position.
+     */
     private static final String STATE_SELECTED_NAVIGATION_ITEM = "selected_navigation_item";
 
     @Override
     public void onCreate(Bundle savedInstanceState) {
         super.onCreate(savedInstanceState);
         setContentView(R.layout.${layoutName});
-        <#if parentActivityClass != "">
-        getActionBar().setDisplayHomeAsUpEnabled(true);
-        </#if>
 
-        // Set up the action bar.
+        // Set up the action bar to show a dropdown list.
         final ActionBar actionBar = getActionBar();
         actionBar.setDisplayShowTitleEnabled(false);
         actionBar.setNavigationMode(ActionBar.NAVIGATION_MODE_LIST);
+        <#if parentActivityClass != "">
+        // Show the Up button in the action bar.
+        actionBar.setDisplayHomeAsUpEnabled(true);
+        </#if>
 
         // Set up the dropdown list navigation in the action bar.
         actionBar.setListNavigationCallbacks(
                 // Specify a SpinnerAdapter to populate the dropdown list.
-                new ArrayAdapter(
-                        actionBar.getThemedContext(),
+                new ArrayAdapter<String>(
+                        <#if minApi gte 14>actionBar.getThemedContext()<#else>getActionBarThemedContextCompat()</#if>,
                         android.R.layout.simple_list_item_1,
                         android.R.id.text1,
-                        new String[]{
+                        new String[] {
                                 getString(R.string.title_section1),
                                 getString(R.string.title_section2),
                                 getString(R.string.title_section3),
@@ -49,8 +54,25 @@ public class ${activityClass} extends FragmentActivity implements ActionBar.OnNa
                 this);
     }
 
+    <#if minApi < 14>
+    /**
+     * Backward-compatible version of {@link ActionBar#getThemedContext()} that
+     * simply returns the {@link android.app.Activity} if
+     * <code>getThemedContext</code> is unavailable.
+     */
+    @TargetApi(Build.VERSION_CODES.ICE_CREAM_SANDWICH)
+    private Context getActionBarThemedContextCompat() {
+        if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.ICE_CREAM_SANDWICH) {
+            return getActionBar().getThemedContext();
+        } else {
+            return this;
+        }
+    }
+    </#if>
+
     @Override
     public void onRestoreInstanceState(Bundle savedInstanceState) {
+        // Restore the previously serialized current dropdown position.
         if (savedInstanceState.containsKey(STATE_SELECTED_NAVIGATION_ITEM)) {
             getActionBar().setSelectedNavigationItem(
                     savedInstanceState.getInt(STATE_SELECTED_NAVIGATION_ITEM));
@@ -59,20 +81,18 @@ public class ${activityClass} extends FragmentActivity implements ActionBar.OnNa
 
     @Override
     public void onSaveInstanceState(Bundle outState) {
+        // Serialize the current dropdown position.
         outState.putInt(STATE_SELECTED_NAVIGATION_ITEM,
                 getActionBar().getSelectedNavigationIndex());
     }
 
-    @Override
-    public boolean onCreateOptionsMenu(Menu menu) {
-        getMenuInflater().inflate(R.menu.${menuName}, menu);
-        return true;
-    }
+    <#include "include_onCreateOptionsMenu.java.ftl">
     <#include "include_onOptionsItemSelected.java.ftl">
 
     @Override
     public boolean onNavigationItemSelected(int position, long id) {
-        // When the given tab is selected, show the tab contents in the container
+        // When the given dropdown item is selected, show its contents in the
+        // container view.
         Fragment fragment = new DummySectionFragment();
         Bundle args = new Bundle();
         args.putInt(DummySectionFragment.ARG_SECTION_NUMBER, position + 1);
@@ -83,23 +103,6 @@ public class ${activityClass} extends FragmentActivity implements ActionBar.OnNa
         return true;
     }
 
-    /**
-     * A dummy fragment representing a section of the app, but that simply displays dummy text.
-     */
-    public static class DummySectionFragment extends Fragment {
-        public DummySectionFragment() {
-        }
-
-        public static final String ARG_SECTION_NUMBER = "section_number";
+    <#include "include_DummySectionFragment.java.ftl">
 
-        @Override
-        public View onCreateView(LayoutInflater inflater, ViewGroup container,
-                Bundle savedInstanceState) {
-            TextView textView = new TextView(getActivity());
-            textView.setGravity(Gravity.CENTER);
-            Bundle args = getArguments();
-            textView.setText(Integer.toString(args.getInt(ARG_SECTION_NUMBER)));
-            return textView;
-        }
-    }
 }
diff --git a/templates/activities/BlankActivity/root/src/app_package/SimpleActivity.java.ftl b/templates/activities/BlankActivity/root/src/app_package/SimpleActivity.java.ftl
index 6021829..a409ad4 100644
--- a/templates/activities/BlankActivity/root/src/app_package/SimpleActivity.java.ftl
+++ b/templates/activities/BlankActivity/root/src/app_package/SimpleActivity.java.ftl
@@ -15,16 +15,12 @@ public class ${activityClass} extends Activity {
         super.onCreate(savedInstanceState);
         setContentView(R.layout.${layoutName});
         <#if parentActivityClass != "">
+        // Show the Up button in the action bar.
         getActionBar().setDisplayHomeAsUpEnabled(true);
         </#if>
     }
 
-    @Override
-    public boolean onCreateOptionsMenu(Menu menu) {
-        getMenuInflater().inflate(R.menu.${menuName}, menu);
-        return true;
-    }
-<#if parentActivityClass != "">
+    <#include "include_onCreateOptionsMenu.java.ftl">
     <#include "include_onOptionsItemSelected.java.ftl">
-</#if>
+
 }
diff --git a/templates/activities/BlankActivity/root/src/app_package/TabsActivity.java.ftl b/templates/activities/BlankActivity/root/src/app_package/TabsActivity.java.ftl
index ba5c26c..b0a2f5d 100644
--- a/templates/activities/BlankActivity/root/src/app_package/TabsActivity.java.ftl
+++ b/templates/activities/BlankActivity/root/src/app_package/TabsActivity.java.ftl
@@ -2,11 +2,9 @@ package ${packageName};
 
 import android.app.ActionBar;
 import android.app.FragmentTransaction;
-import android.content.Context;
 import android.os.Bundle;
 import android.support.v4.app.Fragment;
 import android.support.v4.app.FragmentActivity;
-import android.support.v4.app.FragmentManager;
 import android.support.v4.app.NavUtils;
 import android.view.Gravity;
 import android.view.LayoutInflater;
@@ -18,19 +16,24 @@ import android.widget.TextView;
 
 public class ${activityClass} extends FragmentActivity implements ActionBar.TabListener {
 
+    /**
+     * The serialization (saved instance state) Bundle key representing the
+     * current tab position.
+     */
     private static final String STATE_SELECTED_NAVIGATION_ITEM = "selected_navigation_item";
 
     @Override
     public void onCreate(Bundle savedInstanceState) {
         super.onCreate(savedInstanceState);
         setContentView(R.layout.${layoutName});
-        <#if parentActivityClass != "">
-        getActionBar().setDisplayHomeAsUpEnabled(true);
-        </#if>
 
-        // Set up the action bar.
+        // Set up the action bar to show tabs.
         final ActionBar actionBar = getActionBar();
         actionBar.setNavigationMode(ActionBar.NAVIGATION_MODE_TABS);
+        <#if parentActivityClass != "">
+        // Show the Up button in the action bar.
+        actionBar.setDisplayHomeAsUpEnabled(true);
+        </#if>
 
         // For each of the sections in the app, add a tab to the action bar.
         actionBar.addTab(actionBar.newTab().setText(R.string.title_section1).setTabListener(this));
@@ -40,6 +43,7 @@ public class ${activityClass} extends FragmentActivity implements ActionBar.TabL
 
     @Override
     public void onRestoreInstanceState(Bundle savedInstanceState) {
+        // Restore the previously serialized current tab position.
         if (savedInstanceState.containsKey(STATE_SELECTED_NAVIGATION_ITEM)) {
             getActionBar().setSelectedNavigationItem(
                     savedInstanceState.getInt(STATE_SELECTED_NAVIGATION_ITEM));
@@ -48,24 +52,18 @@ public class ${activityClass} extends FragmentActivity implements ActionBar.TabL
 
     @Override
     public void onSaveInstanceState(Bundle outState) {
+        // Serialize the current tab position.
         outState.putInt(STATE_SELECTED_NAVIGATION_ITEM,
                 getActionBar().getSelectedNavigationIndex());
     }
 
-    @Override
-    public boolean onCreateOptionsMenu(Menu menu) {
-        getMenuInflater().inflate(R.menu.${menuName}, menu);
-        return true;
-    }
+    <#include "include_onCreateOptionsMenu.java.ftl">
     <#include "include_onOptionsItemSelected.java.ftl">
 
     @Override
-    public void onTabUnselected(ActionBar.Tab tab, FragmentTransaction fragmentTransaction) {
-    }
-
-    @Override
     public void onTabSelected(ActionBar.Tab tab, FragmentTransaction fragmentTransaction) {
-        // When the given tab is selected, show the tab contents in the container
+        // When the given tab is selected, show the tab contents in the
+        // container view.
         Fragment fragment = new DummySectionFragment();
         Bundle args = new Bundle();
         args.putInt(DummySectionFragment.ARG_SECTION_NUMBER, tab.getPosition() + 1);
@@ -76,26 +74,13 @@ public class ${activityClass} extends FragmentActivity implements ActionBar.TabL
     }
 
     @Override
-    public void onTabReselected(ActionBar.Tab tab, FragmentTransaction fragmentTransaction) {
+    public void onTabUnselected(ActionBar.Tab tab, FragmentTransaction fragmentTransaction) {
     }
 
-    /**
-     * A dummy fragment representing a section of the app, but that simply displays dummy text.
-     */
-    public static class DummySectionFragment extends Fragment {
-        public DummySectionFragment() {
-        }
+    @Override
+    public void onTabReselected(ActionBar.Tab tab, FragmentTransaction fragmentTransaction) {
+    }
 
-        public static final String ARG_SECTION_NUMBER = "section_number";
+    <#include "include_DummySectionFragment.java.ftl">
 
-        @Override
-        public View onCreateView(LayoutInflater inflater, ViewGroup container,
-                Bundle savedInstanceState) {
-            TextView textView = new TextView(getActivity());
-            textView.setGravity(Gravity.CENTER);
-            Bundle args = getArguments();
-            textView.setText(Integer.toString(args.getInt(ARG_SECTION_NUMBER)));
-            return textView;
-        }
-    }
 }
diff --git a/templates/activities/BlankActivity/root/src/app_package/TabsAndPagerActivity.java.ftl b/templates/activities/BlankActivity/root/src/app_package/TabsAndPagerActivity.java.ftl
index 58f6452..9e82449 100644
--- a/templates/activities/BlankActivity/root/src/app_package/TabsAndPagerActivity.java.ftl
+++ b/templates/activities/BlankActivity/root/src/app_package/TabsAndPagerActivity.java.ftl
@@ -1,8 +1,7 @@
 package ${packageName};
 
-import android.app.ActionBar;
-import android.app.FragmentTransaction;
-import android.content.Context;
+<#if navType?contains("tabs")>import android.app.ActionBar;
+import android.app.FragmentTransaction;</#if>
 import android.os.Bundle;
 import android.support.v4.app.Fragment;
 import android.support.v4.app.FragmentActivity;
@@ -21,10 +20,12 @@ import android.widget.TextView;
 public class ${activityClass} extends FragmentActivity<#if navType?contains("tabs")> implements ActionBar.TabListener</#if> {
 
     /**
-     * The {@link android.support.v4.view.PagerAdapter} that will provide fragments for each of the
-     * sections. We use a {@link android.support.v4.app.FragmentPagerAdapter} derivative, which will
-     * keep every loaded fragment in memory. If this becomes too memory intensive, it may be best
-     * to switch to a {@link android.support.v4.app.FragmentStatePagerAdapter}.
+     * The {@link android.support.v4.view.PagerAdapter} that will provide
+     * fragments for each of the sections. We use a
+     * {@link android.support.v4.app.FragmentPagerAdapter} derivative, which
+     * will keep every loaded fragment in memory. If this becomes too memory
+     * intensive, it may be best to switch to a
+     * {@link android.support.v4.app.FragmentStatePagerAdapter}.
      */
     SectionsPagerAdapter mSectionsPagerAdapter;
 
@@ -37,27 +38,32 @@ public class ${activityClass} extends FragmentActivity<#if navType?contains("tab
     public void onCreate(Bundle savedInstanceState) {
         super.onCreate(savedInstanceState);
         setContentView(R.layout.${layoutName});
-        <#if parentActivityClass != "">
-        getActionBar().setDisplayHomeAsUpEnabled(true);
-        </#if>
-        // Create the adapter that will return a fragment for each of the three primary sections
-        // of the app.
-        mSectionsPagerAdapter = new SectionsPagerAdapter(getSupportFragmentManager());
 
         <#if navType?contains("tabs")>
         // Set up the action bar.
         final ActionBar actionBar = getActionBar();
         actionBar.setNavigationMode(ActionBar.NAVIGATION_MODE_TABS);
+        <#if parentActivityClass != "">
+        // Show the Up button in the action bar.
+        actionBar.setDisplayHomeAsUpEnabled(true);
+        </#if>
+        <#elseif parentActivityClass != "">
+        // Show the Up button in the action bar.
+        getActionBar().setDisplayHomeAsUpEnabled(true);
         </#if>
 
+        // Create the adapter that will return a fragment for each of the three
+        // primary sections of the app.
+        mSectionsPagerAdapter = new SectionsPagerAdapter(getSupportFragmentManager());
+
         // Set up the ViewPager with the sections adapter.
         mViewPager = (ViewPager) findViewById(R.id.pager);
         mViewPager.setAdapter(mSectionsPagerAdapter);
 
         <#if navType?contains("tabs")>
-        // When swiping between different sections, select the corresponding tab.
-        // We can also use ActionBar.Tab#select() to do this if we have a reference to the
-        // Tab.
+        // When swiping between different sections, select the corresponding
+        // tab. We can also use ActionBar.Tab#select() to do this if we have
+        // a reference to the Tab.
         mViewPager.setOnPageChangeListener(new ViewPager.SimpleOnPageChangeListener() {
             @Override
             public void onPageSelected(int position) {
@@ -67,9 +73,10 @@ public class ${activityClass} extends FragmentActivity<#if navType?contains("tab
 
         // For each of the sections in the app, add a tab to the action bar.
         for (int i = 0; i < mSectionsPagerAdapter.getCount(); i++) {
-            // Create a tab with text corresponding to the page title defined by the adapter.
-            // Also specify this Activity object, which implements the TabListener interface, as the
-            // listener for when this tab is selected.
+            // Create a tab with text corresponding to the page title defined by
+            // the adapter. Also specify this Activity object, which implements
+            // the TabListener interface, as the callback (listener) for when
+            // this tab is selected.
             actionBar.addTab(
                     actionBar.newTab()
                             .setText(mSectionsPagerAdapter.getPageTitle(i))
@@ -78,32 +85,27 @@ public class ${activityClass} extends FragmentActivity<#if navType?contains("tab
         </#if>
     }
 
-    @Override
-    public boolean onCreateOptionsMenu(Menu menu) {
-        getMenuInflater().inflate(R.menu.${menuName}, menu);
-        return true;
-    }
+    <#include "include_onCreateOptionsMenu.java.ftl">
     <#include "include_onOptionsItemSelected.java.ftl">
 
-    <#if navType?contains("tabs")>
-    @Override
-    public void onTabUnselected(ActionBar.Tab tab, FragmentTransaction fragmentTransaction) {
+    <#if navType?contains("tabs")>@Override
+    public void onTabSelected(ActionBar.Tab tab, FragmentTransaction fragmentTransaction) {
+        // When the given tab is selected, switch to the corresponding page in
+        // the ViewPager.
+        mViewPager.setCurrentItem(tab.getPosition());
     }
 
     @Override
-    public void onTabSelected(ActionBar.Tab tab, FragmentTransaction fragmentTransaction) {
-        // When the given tab is selected, switch to the corresponding page in the ViewPager.
-        mViewPager.setCurrentItem(tab.getPosition());
+    public void onTabUnselected(ActionBar.Tab tab, FragmentTransaction fragmentTransaction) {
     }
 
     @Override
     public void onTabReselected(ActionBar.Tab tab, FragmentTransaction fragmentTransaction) {
-    }
-    </#if>
+    }</#if>
 
     /**
-     * A {@link FragmentPagerAdapter} that returns a fragment corresponding to one of the primary
-     * sections of the app.
+     * A {@link FragmentPagerAdapter} that returns a fragment corresponding to
+     * one of the sections/tabs/pages.
      */
     public class SectionsPagerAdapter extends FragmentPagerAdapter {
 
@@ -112,47 +114,37 @@ public class ${activityClass} extends FragmentActivity<#if navType?contains("tab
         }
 
         @Override
-        public Fragment getItem(int i) {
+        public Fragment getItem(int position) {
+            // getItem is called to instantiate the fragment for the given page.
+            // Return a DummySectionFragment (defined as a static inner class
+            // below) with the page number as its lone argument.
             Fragment fragment = new DummySectionFragment();
             Bundle args = new Bundle();
-            args.putInt(DummySectionFragment.ARG_SECTION_NUMBER, i + 1);
+            args.putInt(DummySectionFragment.ARG_SECTION_NUMBER, position + 1);
             fragment.setArguments(args);
             return fragment;
         }
 
         @Override
         public int getCount() {
+            // Show 3 total pages.
             return 3;
         }
 
         @Override
         public CharSequence getPageTitle(int position) {
             switch (position) {
-                case 0: return getString(R.string.title_section1).toUpperCase();
-                case 1: return getString(R.string.title_section2).toUpperCase();
-                case 2: return getString(R.string.title_section3).toUpperCase();
+                case 0:
+                    return getString(R.string.title_section1).toUpperCase();
+                case 1:
+                    return getString(R.string.title_section2).toUpperCase();
+                case 2:
+                    return getString(R.string.title_section3).toUpperCase();
             }
             return null;
         }
     }
 
-    /**
-     * A dummy fragment representing a section of the app, but that simply displays dummy text.
-     */
-    public static class DummySectionFragment extends Fragment {
-        public DummySectionFragment() {
-        }
-
-        public static final String ARG_SECTION_NUMBER = "section_number";
+    <#include "include_DummySectionFragment.java.ftl">
 
-        @Override
-        public View onCreateView(LayoutInflater inflater, ViewGroup container,
-                Bundle savedInstanceState) {
-            TextView textView = new TextView(getActivity());
-            textView.setGravity(Gravity.CENTER);
-            Bundle args = getArguments();
-            textView.setText(Integer.toString(args.getInt(ARG_SECTION_NUMBER)));
-            return textView;
-        }
-    }
 }
diff --git a/templates/activities/BlankActivity/root/src/app_package/include_DummySectionFragment.java.ftl b/templates/activities/BlankActivity/root/src/app_package/include_DummySectionFragment.java.ftl
new file mode 100644
index 0000000..c455fc5
--- /dev/null
+++ b/templates/activities/BlankActivity/root/src/app_package/include_DummySectionFragment.java.ftl
@@ -0,0 +1,25 @@
+    /**
+     * A dummy fragment representing a section of the app, but that simply
+     * displays dummy text.
+     */
+    public static class DummySectionFragment extends Fragment {
+        /**
+         * The fragment argument representing the section number for this
+         * fragment.
+         */
+        public static final String ARG_SECTION_NUMBER = "section_number";
+
+        public DummySectionFragment() {
+        }
+
+        @Override
+        public View onCreateView(LayoutInflater inflater, ViewGroup container,
+                Bundle savedInstanceState) {
+            // Create a new TextView and set its text to the fragment's section
+            // number argument value.
+            TextView textView = new TextView(getActivity());
+            textView.setGravity(Gravity.CENTER);
+            textView.setText(Integer.toString(getArguments().getInt(ARG_SECTION_NUMBER)));
+            return textView;
+        }
+    }
diff --git a/templates/activities/BlankActivity/root/src/app_package/include_onCreateOptionsMenu.java.ftl b/templates/activities/BlankActivity/root/src/app_package/include_onCreateOptionsMenu.java.ftl
new file mode 100644
index 0000000..005d629
--- /dev/null
+++ b/templates/activities/BlankActivity/root/src/app_package/include_onCreateOptionsMenu.java.ftl
@@ -0,0 +1,6 @@
+    @Override
+    public boolean onCreateOptionsMenu(Menu menu) {
+        // Inflate the menu; this adds items to the action bar if it is present.
+        getMenuInflater().inflate(R.menu.${menuName}, menu);
+        return true;
+    }
diff --git a/templates/activities/BlankActivity/root/src/app_package/include_onOptionsItemSelected.java.ftl b/templates/activities/BlankActivity/root/src/app_package/include_onOptionsItemSelected.java.ftl
index 001e08f..e1dc462 100644
--- a/templates/activities/BlankActivity/root/src/app_package/include_onOptionsItemSelected.java.ftl
+++ b/templates/activities/BlankActivity/root/src/app_package/include_onOptionsItemSelected.java.ftl
@@ -1,14 +1,19 @@
-
     <#if parentActivityClass != "">
 
     @Override
     public boolean onOptionsItemSelected(MenuItem item) {
         switch (item.getItemId()) {
             case android.R.id.home:
+                // This ID represents the Home or Up button. In the case of this
+                // activity, the Up button is shown. Use NavUtils to allow users
+                // to navigate up one level in the application structure. For
+                // more details, see the Navigation pattern on Android Design:
+                //
+                // http://developer.android.com/design/patterns/navigation.html#up-vs-back
+                //
                 NavUtils.navigateUpFromSameTask(this);
                 return true;
         }
         return super.onOptionsItemSelected(item);
     }
     </#if>
-
diff --git a/templates/activities/BlankActivity/template.xml b/templates/activities/BlankActivity/template.xml
index 00a91e5..bf09e13 100644
--- a/templates/activities/BlankActivity/template.xml
+++ b/templates/activities/BlankActivity/template.xml
@@ -33,10 +33,10 @@
         default="none"
         help="The type of navigation to use for the activity" >
         <option id="none" default="true">None</option>
-        <option id="tabs" minApi="14">Tabs</option>
-        <option id="tabs_pager" minApi="14">Tabs + Swipe</option>
-        <option id="pager_strip" minApi="14">Swipe Views + Title Strip</option>
-        <option id="dropdown" minApi="14">Dropdown</option>
+        <option id="tabs" minApi="11">Tabs</option>
+        <option id="tabs_pager" minApi="11">Tabs + Swipe</option>
+        <option id="pager_strip" minApi="11">Swipe Views + Title Strip</option>
+        <option id="dropdown" minApi="11">Dropdown</option>
     </parameter>
 
     <parameter
diff --git a/templates/activities/MasterDetailFlow/root/AndroidManifest.xml.ftl b/templates/activities/MasterDetailFlow/root/AndroidManifest.xml.ftl
index 3f61bbd..3bd38b8 100644
--- a/templates/activities/MasterDetailFlow/root/AndroidManifest.xml.ftl
+++ b/templates/activities/MasterDetailFlow/root/AndroidManifest.xml.ftl
@@ -2,7 +2,8 @@
 
     <application>
         <activity android:name=".${CollectionName}Activity"
-            android:label="@string/title_${collection_name}">
+            android:label="@string/title_${collection_name}"
+            <#if buildApi gte 16 && parentActivityClass != "">android:parentActivityName="${parentActivityClass}"</#if>>
             <#if parentActivityClass != "">
             <meta-data android:name="android.support.PARENT_ACTIVITY"
                 android:value="${parentActivityClass}" />
@@ -15,7 +16,8 @@
         </activity>
 
         <activity android:name=".${DetailName}Activity"
-            android:label="@string/title_${detail_name}">
+            android:label="@string/title_${detail_name}"
+            <#if buildApi gte 16>android:parentActivityName=".${CollectionName}Activity"</#if>>
             <meta-data android:name="android.support.PARENT_ACTIVITY"
                 android:value=".${CollectionName}Activity" />
         </activity>
diff --git a/templates/activities/MasterDetailFlow/root/res/layout/activity_content_detail.xml.ftl b/templates/activities/MasterDetailFlow/root/res/layout/activity_content_detail.xml.ftl
index fb7ad72..ddc1ecc 100755..100644
--- a/templates/activities/MasterDetailFlow/root/res/layout/activity_content_detail.xml.ftl
+++ b/templates/activities/MasterDetailFlow/root/res/layout/activity_content_detail.xml.ftl
@@ -3,4 +3,5 @@
     android:id="@+id/${detail_name}_container"
     android:layout_width="match_parent"
     android:layout_height="match_parent"
-    tools:context=".${DetailName}Activity" />
+    tools:context=".${DetailName}Activity"
+    tools:ignore="MergeRootFrame" />
diff --git a/templates/activities/MasterDetailFlow/root/res/layout/activity_content_list.xml.ftl b/templates/activities/MasterDetailFlow/root/res/layout/activity_content_list.xml.ftl
index 7f28e72..454af8a 100644
--- a/templates/activities/MasterDetailFlow/root/res/layout/activity_content_list.xml.ftl
+++ b/templates/activities/MasterDetailFlow/root/res/layout/activity_content_list.xml.ftl
@@ -1,7 +1,7 @@
 <fragment xmlns:android="http://schemas.android.com/apk/res/android"
     xmlns:tools="http://schemas.android.com/tools"
-    android:name="${packageName}.${CollectionName}Fragment"
     android:id="@+id/${collection_name}"
+    android:name="${packageName}.${CollectionName}Fragment"
     android:layout_width="match_parent"
     android:layout_height="match_parent"
     android:layout_marginLeft="16dp"
diff --git a/templates/activities/MasterDetailFlow/root/res/layout/activity_content_twopane.xml.ftl b/templates/activities/MasterDetailFlow/root/res/layout/activity_content_twopane.xml.ftl
index 53b37e6..d2b75cc 100644
--- a/templates/activities/MasterDetailFlow/root/res/layout/activity_content_twopane.xml.ftl
+++ b/templates/activities/MasterDetailFlow/root/res/layout/activity_content_twopane.xml.ftl
@@ -1,21 +1,34 @@
 <LinearLayout xmlns:android="http://schemas.android.com/apk/res/android"
     xmlns:tools="http://schemas.android.com/tools"
-    android:orientation="horizontal"
     android:layout_width="match_parent"
     android:layout_height="match_parent"
     android:layout_marginLeft="16dp"
     android:layout_marginRight="16dp"
     android:divider="?android:attr/dividerHorizontal"
+    android:orientation="horizontal"
     android:showDividers="middle"
     tools:context=".${CollectionName}Activity">
 
-    <fragment android:name="${packageName}.${CollectionName}Fragment"
+    <!--
+    This layout is a two-pane layout for the ${objectKindPlural}
+    master/detail flow. See res/values-large/refs.xml and
+    res/values-sw600dp/refs.xml for an example of layout aliases
+    that replace the single-pane version of the layout with
+    this two-pane version.
+
+    For more on layout aliases, see:
+    http://developer.android.com/training/multiscreen/screensizes.html#TaskUseAliasFilters
+    -->
+
+    <fragment
         android:id="@+id/${collection_name}"
+        android:name="${packageName}.${CollectionName}Fragment"
         android:layout_width="0dp"
         android:layout_height="match_parent"
         android:layout_weight="1" />
 
-    <FrameLayout android:id="@+id/${detail_name}_container"
+    <FrameLayout
+        android:id="@+id/${detail_name}_container"
         android:layout_width="0dp"
         android:layout_height="match_parent"
         android:layout_weight="3" />
diff --git a/templates/activities/MasterDetailFlow/root/res/layout/fragment_content_detail.xml.ftl b/templates/activities/MasterDetailFlow/root/res/layout/fragment_content_detail.xml.ftl
index 0a51cb7..d27e1ed 100644
--- a/templates/activities/MasterDetailFlow/root/res/layout/fragment_content_detail.xml.ftl
+++ b/templates/activities/MasterDetailFlow/root/res/layout/fragment_content_detail.xml.ftl
@@ -1,7 +1,7 @@
 <TextView xmlns:android="http://schemas.android.com/apk/res/android"
     xmlns:tools="http://schemas.android.com/tools"
-    style="?android:attr/textAppearanceLarge"
     android:id="@+id/${detail_name}"
+    style="?android:attr/textAppearanceLarge"
     android:layout_width="match_parent"
     android:layout_height="match_parent"
     android:padding="16dp"
diff --git a/templates/activities/MasterDetailFlow/root/res/values-large/refs.xml.ftl b/templates/activities/MasterDetailFlow/root/res/values-large/refs.xml.ftl
index f3edd90..3008e2e 100644
--- a/templates/activities/MasterDetailFlow/root/res/values-large/refs.xml.ftl
+++ b/templates/activities/MasterDetailFlow/root/res/values-large/refs.xml.ftl
@@ -1,3 +1,10 @@
 <resources>
+    <!--
+    Layout alias to replace the single-pane version of the layout with a
+    two-pane version on Large screens.
+
+    For more on layout aliases, see:
+    http://developer.android.com/training/multiscreen/screensizes.html#TaskUseAliasFilters
+    -->
     <item type="layout" name="activity_${collection_name}">@layout/activity_${objectKind?lower_case}_twopane</item>
 </resources>
diff --git a/templates/activities/MasterDetailFlow/root/res/values-sw600dp/refs.xml.ftl b/templates/activities/MasterDetailFlow/root/res/values-sw600dp/refs.xml.ftl
index f3edd90..c698e6e 100644
--- a/templates/activities/MasterDetailFlow/root/res/values-sw600dp/refs.xml.ftl
+++ b/templates/activities/MasterDetailFlow/root/res/values-sw600dp/refs.xml.ftl
@@ -1,3 +1,11 @@
 <resources>
+    <!--
+    Layout alias to replace the single-pane version of the layout with a
+    two-pane version on screens with a smallest width (smallest dimension)
+    of at least 600 density-independent pixels (dips).
+
+    For more on layout aliases, see:
+    http://developer.android.com/training/multiscreen/screensizes.html#TaskUseAliasFilters
+    -->
     <item type="layout" name="activity_${collection_name}">@layout/activity_${objectKind?lower_case}_twopane</item>
 </resources>
diff --git a/templates/activities/MasterDetailFlow/root/src/app_package/ContentDetailActivity.java.ftl b/templates/activities/MasterDetailFlow/root/src/app_package/ContentDetailActivity.java.ftl
index 59a90e2..2cc6054 100644
--- a/templates/activities/MasterDetailFlow/root/src/app_package/ContentDetailActivity.java.ftl
+++ b/templates/activities/MasterDetailFlow/root/src/app_package/ContentDetailActivity.java.ftl
@@ -6,6 +6,15 @@ import android.support.v4.app.FragmentActivity;
 import android.support.v4.app.NavUtils;
 import android.view.MenuItem;
 
+/**
+ * An activity representing a single ${objectKind} detail screen. This
+ * activity is only used on handset devices. On tablet-size devices,
+ * item details are presented side-by-side with a list of items
+ * in a {@link ${CollectionName}Activity}.
+ * <p>
+ * This activity is mostly just a 'shell' activity containing nothing
+ * more than a {@link ${DetailName}Fragment}.
+ */
 public class ${DetailName}Activity extends FragmentActivity {
 
     @Override
@@ -13,9 +22,21 @@ public class ${DetailName}Activity extends FragmentActivity {
         super.onCreate(savedInstanceState);
         setContentView(R.layout.activity_${detail_name});
 
+        // Show the Up button in the action bar.
         getActionBar().setDisplayHomeAsUpEnabled(true);
 
+        // savedInstanceState is non-null when there is fragment state
+        // saved from previous configurations of this activity
+        // (e.g. when rotating the screen from portrait to landscape).
+        // In this case, the fragment will automatically be re-added
+        // to its container so we don't need to manually add it.
+        // For more information, see the Fragments API guide at:
+        //
+        // http://developer.android.com/guide/components/fragments.html
+        //
         if (savedInstanceState == null) {
+            // Create the detail fragment and add it to the activity
+            // using a fragment transaction.
             Bundle arguments = new Bundle();
             arguments.putString(${DetailName}Fragment.ARG_ITEM_ID,
                     getIntent().getStringExtra(${DetailName}Fragment.ARG_ITEM_ID));
@@ -29,11 +50,18 @@ public class ${DetailName}Activity extends FragmentActivity {
 
     @Override
     public boolean onOptionsItemSelected(MenuItem item) {
-        if (item.getItemId() == android.R.id.home) {
-            NavUtils.navigateUpTo(this, new Intent(this, ${CollectionName}Activity.class));
-            return true;
+        switch (item.getItemId()) {
+            case android.R.id.home:
+                // This ID represents the Home or Up button. In the case of this
+                // activity, the Up button is shown. Use NavUtils to allow users
+                // to navigate up one level in the application structure. For
+                // more details, see the Navigation pattern on Android Design:
+                //
+                // http://developer.android.com/design/patterns/navigation.html#up-vs-back
+                //
+                NavUtils.navigateUpTo(this, new Intent(this, ${CollectionName}Activity.class));
+                return true;
         }
-
         return super.onOptionsItemSelected(item);
     }
 }
diff --git a/templates/activities/MasterDetailFlow/root/src/app_package/ContentDetailFragment.java.ftl b/templates/activities/MasterDetailFlow/root/src/app_package/ContentDetailFragment.java.ftl
index a0acb1c..2cecaec 100644
--- a/templates/activities/MasterDetailFlow/root/src/app_package/ContentDetailFragment.java.ftl
+++ b/templates/activities/MasterDetailFlow/root/src/app_package/ContentDetailFragment.java.ftl
@@ -1,7 +1,5 @@
 package ${packageName};
 
-import ${packageName}.dummy.DummyContent;
-
 import android.os.Bundle;
 import android.support.v4.app.Fragment;
 import android.view.LayoutInflater;
@@ -9,19 +7,41 @@ import android.view.View;
 import android.view.ViewGroup;
 import android.widget.TextView;
 
-public class ${DetailName}Fragment extends Fragment {
+import ${packageName}.dummy.DummyContent;
 
+/**
+ * A fragment representing a single ${objectKind} detail screen.
+ * This fragment is either contained in a {@link ${CollectionName}Activity}
+ * in two-pane mode (on tablets) or a {@link ${DetailName}Activity}
+ * on handsets.
+ */
+public class ${DetailName}Fragment extends Fragment {
+    /**
+     * The fragment argument representing the item ID that this fragment
+     * represents.
+     */
     public static final String ARG_ITEM_ID = "item_id";
 
-    DummyContent.DummyItem mItem;
+    /**
+     * The dummy content this fragment is presenting.
+     */
+    private DummyContent.DummyItem mItem;
 
+    /**
+     * Mandatory empty constructor for the fragment manager to instantiate the
+     * fragment (e.g. upon screen orientation changes).
+     */
     public ${DetailName}Fragment() {
     }
 
     @Override
     public void onCreate(Bundle savedInstanceState) {
         super.onCreate(savedInstanceState);
+
         if (getArguments().containsKey(ARG_ITEM_ID)) {
+            // Load the dummy content specified by the fragment
+            // arguments. In a real-world scenario, use a Loader
+            // to load content from a content provider.
             mItem = DummyContent.ITEM_MAP.get(getArguments().getString(ARG_ITEM_ID));
         }
     }
@@ -30,9 +50,12 @@ public class ${DetailName}Fragment extends Fragment {
     public View onCreateView(LayoutInflater inflater, ViewGroup container,
             Bundle savedInstanceState) {
         View rootView = inflater.inflate(R.layout.fragment_${detail_name}, container, false);
+
+        // Show the dummy content as text in a TextView.
         if (mItem != null) {
             ((TextView) rootView.findViewById(R.id.${detail_name})).setText(mItem.content);
         }
+
         return rootView;
     }
 }
diff --git a/templates/activities/MasterDetailFlow/root/src/app_package/ContentListActivity.java.ftl b/templates/activities/MasterDetailFlow/root/src/app_package/ContentListActivity.java.ftl
index 4456815..cbd815e 100644
--- a/templates/activities/MasterDetailFlow/root/src/app_package/ContentListActivity.java.ftl
+++ b/templates/activities/MasterDetailFlow/root/src/app_package/ContentListActivity.java.ftl
@@ -3,14 +3,32 @@ package ${packageName};
 import android.content.Intent;
 import android.os.Bundle;
 import android.support.v4.app.FragmentActivity;
-<#if parentActivityClass != "">
-import android.support.v4.app.NavUtils;
-import android.view.MenuItem;
-</#if>
+<#if parentActivityClass != "">import android.support.v4.app.NavUtils;
+import android.view.MenuItem;</#if>
 
+/**
+ * An activity representing a list of ${objectKindPlural}. This activity
+ * has different presentations for handset and tablet-size devices. On
+ * handsets, the activity presents a list of items, which when touched,
+ * lead to a {@link ${DetailName}Activity} representing
+ * item details. On tablets, the activity presents the list of items and
+ * item details side-by-side using two vertical panes.
+ * <p>
+ * The activity makes heavy use of fragments. The list of items is a
+ * {@link ${CollectionName}Fragment} and the item details
+ * (if present) is a {@link ${DetailName}Fragment}.
+ * <p>
+ * This activity also implements the required
+ * {@link ${CollectionName}Fragment.Callbacks} interface
+ * to listen for item selections.
+ */
 public class ${CollectionName}Activity extends FragmentActivity
         implements ${CollectionName}Fragment.Callbacks {
 
+    /**
+     * Whether or not the activity is in two-pane mode, i.e. running on a tablet
+     * device.
+     */
     private boolean mTwoPane;
 
     @Override
@@ -18,15 +36,25 @@ public class ${CollectionName}Activity extends FragmentActivity
         super.onCreate(savedInstanceState);
         setContentView(R.layout.activity_${collection_name});
         <#if parentActivityClass != "">
+        // Show the Up button in the action bar.
         getActionBar().setDisplayHomeAsUpEnabled(true);
         </#if>
 
         if (findViewById(R.id.${detail_name}_container) != null) {
+            // The detail container view will be present only in the
+            // large-screen layouts (res/values-large and
+            // res/values-sw600dp). If this view is present, then the
+            // activity should be in two-pane mode.
             mTwoPane = true;
+
+            // In two-pane mode, list items should be given the
+            // 'activated' state when touched.
             ((${CollectionName}Fragment) getSupportFragmentManager()
                     .findFragmentById(R.id.${collection_name}))
                     .setActivateOnItemClick(true);
         }
+
+        // TODO: If exposing deep links into your app, handle intents here.
     }
     <#if parentActivityClass != "">
 
@@ -34,6 +62,13 @@ public class ${CollectionName}Activity extends FragmentActivity
     public boolean onOptionsItemSelected(MenuItem item) {
         switch (item.getItemId()) {
             case android.R.id.home:
+                // This ID represents the Home or Up button. In the case of this
+                // activity, the Up button is shown. Use NavUtils to allow users
+                // to navigate up one level in the application structure. For
+                // more details, see the Navigation pattern on Android Design:
+                //
+                // http://developer.android.com/design/patterns/navigation.html#up-vs-back
+                //
                 NavUtils.navigateUpFromSameTask(this);
                 return true;
         }
@@ -41,9 +76,16 @@ public class ${CollectionName}Activity extends FragmentActivity
     }
     </#if>
 
+    /**
+     * Callback method from {@link ${CollectionName}Fragment.Callbacks}
+     * indicating that the item with the given ID was selected.
+     */
     @Override
     public void onItemSelected(String id) {
         if (mTwoPane) {
+            // In two-pane mode, show the detail view in this activity by
+            // adding or replacing the detail fragment using a
+            // fragment transaction.
             Bundle arguments = new Bundle();
             arguments.putString(${DetailName}Fragment.ARG_ITEM_ID, id);
             ${DetailName}Fragment fragment = new ${DetailName}Fragment();
@@ -53,6 +95,8 @@ public class ${CollectionName}Activity extends FragmentActivity
                     .commit();
 
         } else {
+            // In single-pane mode, simply start the detail activity
+            // for the selected item ID.
             Intent detailIntent = new Intent(this, ${DetailName}Activity.class);
             detailIntent.putExtra(${DetailName}Fragment.ARG_ITEM_ID, id);
             startActivity(detailIntent);
diff --git a/templates/activities/MasterDetailFlow/root/src/app_package/ContentListFragment.java.ftl b/templates/activities/MasterDetailFlow/root/src/app_package/ContentListFragment.java.ftl
index 7de2868..e9a2e74 100644
--- a/templates/activities/MasterDetailFlow/root/src/app_package/ContentListFragment.java.ftl
+++ b/templates/activities/MasterDetailFlow/root/src/app_package/ContentListFragment.java.ftl
@@ -1,7 +1,5 @@
 package ${packageName};
 
-import ${packageName}.dummy.DummyContent;
-
 import android.app.Activity;
 import android.os.Bundle;
 import android.support.v4.app.ListFragment;
@@ -9,31 +7,72 @@ import android.view.View;
 import android.widget.ArrayAdapter;
 import android.widget.ListView;
 
+import ${packageName}.dummy.DummyContent;
+
+/**
+ * A list fragment representing a list of ${objectKindPlural}. This fragment
+ * also supports tablet devices by allowing list items to be given an
+ * 'activated' state upon selection. This helps indicate which item is
+ * currently being viewed in a {@link ${DetailName}Fragment}.
+ * <p>
+ * Activities containing this fragment MUST implement the {@link Callbacks}
+ * interface.
+ */
 public class ${CollectionName}Fragment extends ListFragment {
 
+    /**
+     * The serialization (saved instance state) Bundle key representing the
+     * activated item position. Only used on tablets.
+     */
     private static final String STATE_ACTIVATED_POSITION = "activated_position";
 
+    /**
+     * The fragment's current callback object, which is notified of list item
+     * clicks.
+     */
     private Callbacks mCallbacks = sDummyCallbacks;
+
+    /**
+     * The current activated item position. Only used on tablets.
+     */
     private int mActivatedPosition = ListView.INVALID_POSITION;
 
+    /**
+     * A callback interface that all activities containing this fragment must
+     * implement. This mechanism allows activities to be notified of item
+     * selections.
+     */
     public interface Callbacks {
-
+        /**
+         * Callback for when an item has been selected.
+         */
         public void onItemSelected(String id);
     }
 
+    /**
+     * A dummy implementation of the {@link Callbacks} interface that does
+     * nothing. Used only when this fragment is not attached to an activity.
+     */
     private static Callbacks sDummyCallbacks = new Callbacks() {
         @Override
         public void onItemSelected(String id) {
         }
     };
 
+    /**
+     * Mandatory empty constructor for the fragment manager to instantiate the
+     * fragment (e.g. upon screen orientation changes).
+     */
     public ${CollectionName}Fragment() {
     }
 
     @Override
     public void onCreate(Bundle savedInstanceState) {
         super.onCreate(savedInstanceState);
-        setListAdapter(new ArrayAdapter<DummyContent.DummyItem>(getActivity(),
+
+        // TODO: replace with a real list adapter.
+        setListAdapter(new ArrayAdapter<DummyContent.DummyItem>(
+                getActivity(),
                 android.R.layout.simple_list_item_activated_1,
                 android.R.id.text1,
                 DummyContent.ITEMS));
@@ -42,8 +81,10 @@ public class ${CollectionName}Fragment extends ListFragment {
     @Override
     public void onViewCreated(View view, Bundle savedInstanceState) {
         super.onViewCreated(view, savedInstanceState);
-        if (savedInstanceState != null && savedInstanceState
-                .containsKey(STATE_ACTIVATED_POSITION)) {
+
+        // Restore the previously serialized activated item position.
+        if (savedInstanceState != null
+                && savedInstanceState.containsKey(STATE_ACTIVATED_POSITION)) {
             setActivatedPosition(savedInstanceState.getInt(STATE_ACTIVATED_POSITION));
         }
     }
@@ -51,6 +92,8 @@ public class ${CollectionName}Fragment extends ListFragment {
     @Override
     public void onAttach(Activity activity) {
         super.onAttach(activity);
+
+        // Activities containing this fragment must implement its callbacks.
         if (!(activity instanceof Callbacks)) {
             throw new IllegalStateException("Activity must implement fragment's callbacks.");
         }
@@ -61,12 +104,17 @@ public class ${CollectionName}Fragment extends ListFragment {
     @Override
     public void onDetach() {
         super.onDetach();
+
+        // Reset the active callbacks interface to the dummy implementation.
         mCallbacks = sDummyCallbacks;
     }
 
     @Override
     public void onListItemClick(ListView listView, View view, int position, long id) {
         super.onListItemClick(listView, view, position, id);
+
+        // Notify the active callbacks interface (the activity, if the
+        // fragment is attached to one) that an item has been selected.
         mCallbacks.onItemSelected(DummyContent.ITEMS.get(position).id);
     }
 
@@ -74,17 +122,24 @@ public class ${CollectionName}Fragment extends ListFragment {
     public void onSaveInstanceState(Bundle outState) {
         super.onSaveInstanceState(outState);
         if (mActivatedPosition != ListView.INVALID_POSITION) {
+            // Serialize and persist the activated item position.
             outState.putInt(STATE_ACTIVATED_POSITION, mActivatedPosition);
         }
     }
 
+    /**
+     * Turns on activate-on-click mode. When this mode is on, list items will be
+     * given the 'activated' state when touched.
+     */
     public void setActivateOnItemClick(boolean activateOnItemClick) {
+        // When setting CHOICE_MODE_SINGLE, ListView will automatically
+        // give items the 'activated' state when touched.
         getListView().setChoiceMode(activateOnItemClick
                 ? ListView.CHOICE_MODE_SINGLE
                 : ListView.CHOICE_MODE_NONE);
     }
 
-    public void setActivatedPosition(int position) {
+    private void setActivatedPosition(int position) {
         if (position == ListView.INVALID_POSITION) {
             getListView().setItemChecked(mActivatedPosition, false);
         } else {
diff --git a/templates/activities/MasterDetailFlow/root/src/app_package/dummy/DummyContent.java.ftl b/templates/activities/MasterDetailFlow/root/src/app_package/dummy/DummyContent.java.ftl
index 2b05416..3545ba3 100644
--- a/templates/activities/MasterDetailFlow/root/src/app_package/dummy/DummyContent.java.ftl
+++ b/templates/activities/MasterDetailFlow/root/src/app_package/dummy/DummyContent.java.ftl
@@ -5,10 +5,40 @@ import java.util.HashMap;
 import java.util.List;
 import java.util.Map;
 
+/**
+ * Helper class for providing sample content for user interfaces created by
+ * Android template wizards.
+ * <p>
+ * TODO: Replace all uses of this class before publishing your app.
+ */
 public class DummyContent {
 
-    public static class DummyItem {
+    /**
+     * An array of sample (dummy) items.
+     */
+    public static List<DummyItem> ITEMS = new ArrayList<DummyItem>();
+
+    /**
+     * A map of sample (dummy) items, by ID.
+     */
+    public static Map<String, DummyItem> ITEM_MAP = new HashMap<String, DummyItem>();
+
+    static {
+        // Add 3 sample items.
+        addItem(new DummyItem("1", "Item 1"));
+        addItem(new DummyItem("2", "Item 2"));
+        addItem(new DummyItem("3", "Item 3"));
+    }
+
+    private static void addItem(DummyItem item) {
+        ITEMS.add(item);
+        ITEM_MAP.put(item.id, item);
+    }
 
+    /**
+     * A dummy item representing a piece of content.
+     */
+    public static class DummyItem {
         public String id;
         public String content;
 
@@ -22,18 +52,4 @@ public class DummyContent {
             return content;
         }
     }
-
-    public static List<DummyItem> ITEMS = new ArrayList<DummyItem>();
-    public static Map<String, DummyItem> ITEM_MAP = new HashMap<String, DummyItem>();
-
-    static {
-        addItem(new DummyItem("1", "Item 1"));
-        addItem(new DummyItem("2", "Item 2"));
-        addItem(new DummyItem("3", "Item 3"));
-    }
-
-    private static void addItem(DummyItem item) {
-        ITEMS.add(item);
-        ITEM_MAP.put(item.id, item);
-    }
 }
diff --git a/templates/projects/NewAndroidApplication/root/res/drawable-hdpi/ic_action_search.png b/templates/projects/NewAndroidApplication/root/res/drawable-hdpi/ic_action_search.png
deleted file mode 100644
index 67de12d..0000000
--- a/templates/projects/NewAndroidApplication/root/res/drawable-hdpi/ic_action_search.png
+++ /dev/null
diff --git a/templates/projects/NewAndroidApplication/root/res/drawable-mdpi/ic_action_search.png b/templates/projects/NewAndroidApplication/root/res/drawable-mdpi/ic_action_search.png
deleted file mode 100644
index 134d549..0000000
--- a/templates/projects/NewAndroidApplication/root/res/drawable-mdpi/ic_action_search.png
+++ /dev/null
diff --git a/templates/projects/NewAndroidApplication/root/res/drawable-xhdpi/ic_action_search.png b/templates/projects/NewAndroidApplication/root/res/drawable-xhdpi/ic_action_search.png
deleted file mode 100644
index d699c6b..0000000
--- a/templates/projects/NewAndroidApplication/root/res/drawable-xhdpi/ic_action_search.png
+++ /dev/null
diff --git a/templates/projects/NewAndroidApplication/template.xml b/templates/projects/NewAndroidApplication/template.xml
index c1266f2..184844f 100644
--- a/templates/projects/NewAndroidApplication/template.xml
+++ b/templates/projects/NewAndroidApplication/template.xml
@@ -49,14 +49,14 @@
         name="Target API level"
         type="string"
         constraints="apilevel"
-        default="15" />
+        default="16" />
 
     <parameter
         id="buildApi"
         name="Build API level"
         type="string"
         constraints="apilevel"
-        default="15" />
+        default="16" />
 
     <parameter
         id="copyIcons"