Add offline docs target for support lib gradle build

Fixes standalone docs issues like references to hidden framework class
R.styleable. Removes reference to BackupAgent, which makes doclava choke
for some unknown reason.

Standalone online docs may now be built with ./gradlew :generateDocs

Bug: 28124434
Change-Id: If76ac9018be1d17f1258802d4ef3ce1ad67b4903

Author: alanv

Android.mk

@@ -69,6 +69,12 @@ check-support-api: PRIVATE_LOCAL_PATH := $(LOCAL_PATH)
 check-support-api:
 	$(PRIVATE_LOCAL_PATH)/gradlew -p $(PRIVATE_LOCAL_PATH) checkApi
 
+# Proxy to gradle task for generating docs
+.PHONY: support-docs
+support-docs: PRIVATE_LOCAL_PATH := $(LOCAL_PATH)
+support-docs:
+	$(PRIVATE_LOCAL_PATH)/gradlew -p $(PRIVATE_LOCAL_PATH) generateDocs
+
 # Pre-process support library AIDLs
 aidl_files := $(addprefix $(LOCAL_PATH)/, $(call all-subdir-named-files-exclude,*.aidl,I*.aidl))
 support-aidl := $(TARGET_OUT_COMMON_INTERMEDIATES)/support.aidl

build.gradle

@@ -1,3 +1,4 @@
+import android.support.doclava.DoclavaMultilineJavadocOptionFileOption
 import com.android.build.gradle.internal.coverage.JacocoReportTask
 import com.android.build.gradle.internal.tasks.DeviceProviderInstrumentTestTask
 
@@ -253,24 +254,50 @@ void setApiModuleDependencies(Project subProject, DependencyHandler handler, Lis
     }
 }
 
-void registerForDocs(Project subProject, releaseVariant) {
-    rootProject.generateApi.dependsOn releaseVariant.javaCompile
-    rootProject.generateApi.source {
+void registerForDocsTask(Task task, Project subProject, releaseVariant) {
+    task.dependsOn releaseVariant.javaCompile
+    task.source {
         def buildConfig = fileTree(releaseVariant.getGenerateBuildConfig().sourceOutputDir)
         return releaseVariant.javaCompile.source.minus(buildConfig) +
             fileTree(releaseVariant.aidlCompile.sourceOutputDir) +
             fileTree(releaseVariant.outputs[0].processResources.sourceOutputDir)
     }
-    rootProject.generateApi.classpath += files(releaseVariant.javaCompile.classpath) +
+    task.classpath += files(releaseVariant.javaCompile.classpath) +
             files(releaseVariant.javaCompile.destinationDir)
 
     if (subProject.hasProperty('allSS')) {
         subProject.allSS.each { ss ->
-            rootProject.generateApi.source ss.java
+            task.source ss.java
         }
     }
 }
 
+// Generates online docs.
+task generateDocs(type: DoclavaTask, dependsOn: configurations.doclava) {
+    docletpath = configurations.doclava.resolve()
+    destinationDir = new File(project.docsDir, "online")
+
+    // Base classpath is Android SDK, sub-projects add their own.
+    classpath = getAndroidPrebuilt(gradle.ext.currentSdk)
+
+    def hdfOption = new DoclavaMultilineJavadocOptionFileOption('hdf')
+    hdfOption.add(
+            ['android.whichdoc', 'online'],
+            ['android.hasSamples', 'true']);
+
+    options {
+        addStringOption "templatedir",
+                "${project.rootDir}/../../build/tools/droiddoc/templates-sdk"
+        addStringOption "federate Android", "http://developer.android.com"
+        addStringOption "federationapi Android",
+                "${project.rootDir}/../../prebuilts/sdk/api/24.txt"
+        addStringOption "stubpackages", "android.support.*"
+        addStringOption "samplesdir", "${project.rootDir}/samples"
+        addOption hdfOption
+    }
+
+    exclude '**/BuildConfig.java'
+}
 
 // Generates API files.
 task generateApi(type: DoclavaTask, dependsOn: configurations.doclava) {
@@ -462,7 +489,8 @@ subprojects {
                 && !(p.android.hasProperty('noDocs') && p.android.noDocs)) {
             p.android.libraryVariants.all { v ->
                 if (v.name == 'release') {
-                    registerForDocs(p, v)
+                    registerForDocsTask(rootProject.generateDocs, p, v)
+                    registerForDocsTask(rootProject.generateApi, p, v)
                 }
             }
         }

compat/java/android/support/v4/app/ActivityOptionsCompat.java

@@ -273,8 +273,8 @@ public static ActivityOptionsCompat makeSceneTransitionAnimation(Activity activi
      * In addition, the new task wil be affiliated with the launching activity's task.
      * Affiliated tasks are grouped together in the recents task list.
      *
-     * <p>This behavior is not supported for activities with {@link
-     * android.R.styleable#AndroidManifestActivity_launchMode launchMode} values of
+     * <p>This behavior is not supported for activities with
+     * {@link android.R.attr#launchMode launchMode} values of
      * <code>singleInstance</code> or <code>singleTask</code>.
      */
     public static ActivityOptionsCompat makeTaskLaunchBehind() {

compat/java/android/support/v4/content/ContextCompat.java

@@ -422,17 +422,15 @@ public static int checkSelfPermission(@NonNull Context context, @NonNull String
      * Returns the absolute path to the directory on the filesystem similar to
      * {@link Context#getFilesDir()}.  The difference is that files placed under this
      * directory will be excluded from automatic backup to remote storage on
-     * devices running {@link android.os.Build.VERSION_CODES#LOLLIPOP} or later.  See
-     * {@link android.app.backup.BackupAgent BackupAgent} for a full discussion
-     * of the automatic backup mechanism in Android.
+     * devices running {@link android.os.Build.VERSION_CODES#LOLLIPOP} or later.
      *
      * <p>No permissions are required to read or write to the returned path, since this
      * path is internal storage.
      *
      * @return The path of the directory holding application files that will not be
      *         automatically backed up to remote storage.
      *
-     * @see android.content.Context.getFilesDir
+     * @see android.content.Context#getFilesDir()
      */
     public static final File getNoBackupFilesDir(Context context) {
         final int version = Build.VERSION.SDK_INT;

compat/java/android/support/v4/widget/TextViewCompat.java

@@ -269,9 +269,7 @@ public static int getMinLines(@NonNull TextView textView) {
      * Sets the text appearance from the specified style resource.
      * <p>
      * Use a framework-defined {@code TextAppearance} style like
-     * {@link android.R.style#TextAppearance_Material_Body1 @android:style/TextAppearance.Material.Body1}
-     * or see {@link android.R.styleable#TextAppearance TextAppearance} for the
-     * set of attributes that can be used in a custom style.
+     * {@link android.R.style#TextAppearance_Material_Body1 @android:style/TextAppearance.Material.Body1}.
      *
      * @param textView The TextView against which to invoke the method.
      * @param resId    The resource identifier of the style to apply.

fragment/java/android/support/v4/app/Fragment.java

@@ -30,21 +30,21 @@
 import android.support.annotation.NonNull;
 import android.support.annotation.Nullable;
 import android.support.annotation.StringRes;
-import android.support.v4.util.SimpleArrayMap;
 import android.support.v4.util.DebugUtils;
+import android.support.v4.util.SimpleArrayMap;
 import android.support.v4.view.LayoutInflaterCompat;
 import android.util.AttributeSet;
 import android.util.Log;
 import android.util.SparseArray;
 import android.view.ContextMenu;
+import android.view.ContextMenu.ContextMenuInfo;
 import android.view.LayoutInflater;
 import android.view.Menu;
 import android.view.MenuInflater;
 import android.view.MenuItem;
 import android.view.View;
-import android.view.ViewGroup;
-import android.view.ContextMenu.ContextMenuInfo;
 import android.view.View.OnCreateContextMenuListener;
+import android.view.ViewGroup;
 import android.view.animation.Animation;
 import android.widget.AdapterView;
 
@@ -1139,24 +1139,24 @@ public LayoutInflater getLayoutInflater(Bundle savedInstanceState) {
      * <p>Here is a typical implementation of a fragment that can take parameters
      * both through attributes supplied here as well from {@link #getArguments()}:</p>
      *
-     * {@sample development/samples/ApiDemos/src/com/example/android/apis/app/FragmentArguments.java
+     * {@sample frameworks/support/samples/Support4Demos/src/com/example/android/supportv4/app/FragmentArgumentsSupport.java
      *      fragment}
      *
      * <p>Note that parsing the XML attributes uses a "styleable" resource.  The
      * declaration for the styleable used here is:</p>
      *
-     * {@sample development/samples/ApiDemos/res/values/attrs.xml fragment_arguments}
+     * {@sample frameworks/support/samples/Support4Demos/res/values/attrs.xml fragment_arguments}
      * 
      * <p>The fragment can then be declared within its activity's content layout
      * through a tag like this:</p>
      *
-     * {@sample development/samples/ApiDemos/res/layout/fragment_arguments.xml from_attributes}
+     * {@sample frameworks/support/samples/Support4Demos/res/layout/fragment_arguments_support.xml from_attributes}
      *
      * <p>This fragment can also be created dynamically from arguments given
      * at runtime in the arguments Bundle; here is an example of doing so at
      * creation of the containing activity:</p>
      *
-     * {@sample development/samples/ApiDemos/src/com/example/android/apis/app/FragmentArguments.java
+     * {@sample frameworks/support/samples/Support4Demos/src/com/example/android/supportv4/app/FragmentArgumentsSupport.java
      *      create}
      *
      * @param context The Activity that is inflating this fragment.

frameworks/support/samples

@@ -0,0 +1 @@
+../../samples/

transition/src/android/support/transition/Transition.java

@@ -49,8 +49,8 @@
  * and resizing the view) may be out of sync with the display inside those bounds.
  * TextureView is more compatible with transitions in general, but some
  * specific transitions (such as {@link Fade}) may not be compatible
- * with TextureView because they rely on {@link ViewOverlay} functionality,
- * which does not currently work with TextureView.</p>
+ * with TextureView because they rely on {@link android.view.ViewOverlay}
+ * functionality, which does not currently work with TextureView.</p>
  *
  * <p>Unlike the platform version, this does not support declaration by XML resources.</p>
  */
@@ -445,7 +445,7 @@ public long getDuration() {
      *
      * @param duration The length of the animation, in milliseconds.
      * @return This transition object.
-     * @attr ref android.R.styleable#Transition_duration
+     * @attr name android:duration
      */
     @NonNull
     public Transition setDuration(long duration) {
@@ -474,7 +474,7 @@ public TimeInterpolator getInterpolator() {
      *
      * @param interpolator The time interpolator used by the transition
      * @return This transition object.
-     * @attr ref android.R.styleable#Transition_interpolator
+     * @attr name android:interpolator
      */
     @NonNull
     public Transition setInterpolator(@Nullable TimeInterpolator interpolator) {
@@ -519,7 +519,7 @@ public long getStartDelay() {
      *
      * @param startDelay The length of the delay, in milliseconds.
      * @return This transition object.
-     * @attr ref android.R.styleable#Transition_startDelay
+     * @attr name android:startDelay
      */
     @NonNull
     public Transition setStartDelay(long startDelay) {

transition/src/android/support/transition/Visibility.java

@@ -27,7 +27,7 @@
  * start and end scenes. Visibility is determined not just by the
  * {@link View#setVisibility(int)} state of views, but also whether
  * views exist in the current view hierarchy. The class is intended to be a
- * utility for subclasses such as {@link FadePort}, which use this visibility
+ * utility for subclasses such as {@link Fade}, which use this visibility
  * information to determine the specific animations to run when visibility
  * changes occur. Subclasses should implement one or both of the methods
  * {@link #onAppear(ViewGroup, TransitionValues, int, TransitionValues, int)},

v7/appcompat/src/android/support/v7/app/ActionBar.java

@@ -26,7 +26,6 @@
 import android.support.annotation.Nullable;
 import android.support.annotation.StringRes;
 import android.support.v4.app.Fragment;
-import android.support.v4.app.FragmentManager;
 import android.support.v4.app.FragmentTransaction;
 import android.support.v4.view.GravityCompat;
 import android.support.v7.appcompat.R;
@@ -604,12 +603,6 @@ public void setSplitBackgroundDrawable(Drawable d) { }
      * Create and return a new {@link Tab}.
      * This tab will not be included in the action bar until it is added.
      *
-     * <p>Very often tabs will be used to switch between {@link Fragment}
-     * objects.  Here is a typical implementation of such tabs:</p>
-     *
-     * {@sample development/samples/ApiDemos/src/com/example/android/apis/app/FragmentTabs.java
-     *      complete}
-     *
      * @return A new Tab
      *
      * @see #addTab(Tab)