|
| 1 | +// Copyright 2021 Google LLC |
| 2 | +// |
| 3 | +// Licensed under the Apache License, Version 2.0 (the "License"); |
| 4 | +// you may not use this file except in compliance with the License. |
| 5 | +// You may obtain a copy of the License at |
| 6 | +// |
| 7 | +// http://www.apache.org/licenses/LICENSE-2.0 |
| 8 | +// |
| 9 | +// Unless required by applicable law or agreed to in writing, software |
| 10 | +// distributed under the License is distributed on an "AS IS" BASIS, |
| 11 | +// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. |
| 12 | +// See the License for the specific language governing permissions and |
| 13 | +// limitations under the License. |
| 14 | +package com.google.firebase.gradle.plugins; |
| 15 | + |
| 16 | +import static com.google.firebase.gradle.plugins.ProjectUtilsKt.toBoolean; |
| 17 | +import static com.google.firebase.gradle.plugins.ClosureUtil.closureOf; |
| 18 | + |
| 19 | +import com.android.build.gradle.LibraryExtension; |
| 20 | +import com.google.common.collect.ImmutableList; |
| 21 | +import com.google.common.collect.ImmutableMap; |
| 22 | +import java.io.File; |
| 23 | +import java.io.IOException; |
| 24 | +import java.util.List; |
| 25 | +import java.util.Map; |
| 26 | +import org.gradle.api.GradleException; |
| 27 | +import org.gradle.api.Plugin; |
| 28 | +import org.gradle.api.Project; |
| 29 | +import org.gradle.api.Task; |
| 30 | +import org.gradle.api.artifacts.Configuration; |
| 31 | +import org.gradle.api.attributes.Attribute; |
| 32 | +import org.gradle.api.file.FileCollection; |
| 33 | +import org.gradle.api.plugins.JavaPluginConvention; |
| 34 | +import org.gradle.api.tasks.javadoc.Javadoc; |
| 35 | +import org.gradle.external.javadoc.CoreJavadocOptions; |
| 36 | +import org.jetbrains.dokka.gradle.DokkaAndroidPlugin; |
| 37 | +import org.jetbrains.dokka.gradle.DokkaTask; |
| 38 | + |
| 39 | +/** |
| 40 | + * This plugin modifies the java plugin's javadoc task to be firebase friendly. It does the |
| 41 | + * following |
| 42 | + * |
| 43 | + * <ul> |
| 44 | + * <li>It adds android's source sets to the task's sources. |
| 45 | + * <li>It changes the classpath to include ANDROID_HOME |
| 46 | + * <li>Since firebase documents are generated by the doclava doclet, we wire in sensible defaults |
| 47 | + * to enable building javadocs externally while supporting our internal publishing process. |
| 48 | + * <li>Kotlin projects use dokka to produce documentation |
| 49 | + * <li>Projects with `publishJavadoc = false` produce an empty javadoc |
| 50 | + * </ul> |
| 51 | + */ |
| 52 | +public class JavadocPlugin implements Plugin<Project> { |
| 53 | + |
| 54 | + private static final String UNFILTERED_API_TXT_BUILD_PATH = "tmp/javadoc/unfiltered-api.txt"; |
| 55 | + |
| 56 | + @Override |
| 57 | + public void apply(Project project) { |
| 58 | + project.afterEvaluate( |
| 59 | + p -> { |
| 60 | + FirebaseLibraryExtension ext = |
| 61 | + project.getExtensions().findByType(FirebaseLibraryExtension.class); |
| 62 | + if (ext == null) { |
| 63 | + project |
| 64 | + .getLogger() |
| 65 | + .lifecycle( |
| 66 | + "[Doclava] Project {} is not a firebase library, skipping...", |
| 67 | + project.getPath()); |
| 68 | + return; |
| 69 | + } |
| 70 | + @SuppressWarnings("unchecked") |
| 71 | + boolean includeFireEscapeArtifacts = |
| 72 | + toBoolean( |
| 73 | + ((Map<String, Object>) project.getProperties()) |
| 74 | + .getOrDefault("includeFireEscapeArtifacts", "false")); |
| 75 | + if (!ext.publishJavadoc || !includeFireEscapeArtifacts) { |
| 76 | + applyDummyJavadoc(project); |
| 77 | + } else if (project.getPlugins().hasPlugin("kotlin-android")) { |
| 78 | + applyDokka(project); |
| 79 | + } else { |
| 80 | + applyDoclava(project); |
| 81 | + } |
| 82 | + }); |
| 83 | + } |
| 84 | + |
| 85 | + private static void applyDoclava(Project project) { |
| 86 | + project.getConfigurations().maybeCreate("javadocCustomConfig"); |
| 87 | + project.getDependencies().add("javadocCustomConfig", "com.google.doclava:doclava:1.0.6"); |
| 88 | + |
| 89 | + // setting overwrite as java-library adds the javadoc task by default and it does not work |
| 90 | + // with our @hide tags. |
| 91 | + Javadoc generateJavadoc = project.getTasks().replace("generateJavadoc", Javadoc.class); |
| 92 | + project.configure( |
| 93 | + generateJavadoc, |
| 94 | + closureOf( |
| 95 | + (Javadoc javadoc) -> { |
| 96 | + project.getTasks().all(it -> { |
| 97 | + if (it.getName().equals("assembleRelease")) { |
| 98 | + javadoc.dependsOn(it); |
| 99 | + } |
| 100 | + }); |
| 101 | + // Besides third party libraries, firestore depends on the sibling module |
| 102 | + // :immutable-collection, |
| 103 | + // which needs to be in the classpath when javadoc is run |
| 104 | + // Ref: |
| 105 | + // https://stackoverflow.com/questions/41076271/javadoc-generation-error-package-does-not-exist-in-multi-module-project |
| 106 | + if (ProjectUtilsKt.isAndroid(project)) { |
| 107 | + LibraryExtension android = |
| 108 | + project.getExtensions().getByType(LibraryExtension.class); |
| 109 | + javadoc.setClasspath( |
| 110 | + javadoc.getClasspath().plus(project.files(android.getBootClasspath()))); |
| 111 | + // We include the Timestamp file in common's javadoc source set and remove it from |
| 112 | + // Firestore"s source set |
| 113 | + // This comes with the risks of Timestamp's javadoc and binary releases having |
| 114 | + // disconnected timelines. |
| 115 | + // Given the repeated tedium in dealing with javadoc, this risk seems worth taking |
| 116 | + if ("firebase-common".equals(project.getName())) { |
| 117 | + Project firestoreProject = project.findProject(":firebase-firestore"); |
| 118 | + javadoc.setSource( |
| 119 | + android |
| 120 | + .getSourceSets() |
| 121 | + .getByName("main") |
| 122 | + .getJava() |
| 123 | + .getSourceFiles() |
| 124 | + .plus( |
| 125 | + firestoreProject.files( |
| 126 | + "src/main/java/com/google/firebase/Timestamp.java"))); |
| 127 | + |
| 128 | + } else if ("firebase-firestore".equals(project.getName())) { |
| 129 | + javadoc.setSource( |
| 130 | + android |
| 131 | + .getSourceSets() |
| 132 | + .getByName("main") |
| 133 | + .getJava() |
| 134 | + .getSourceFiles() |
| 135 | + .minus( |
| 136 | + project.files("src/main/java/com/google/firebase/Timestamp.java"))); |
| 137 | + } else { |
| 138 | + javadoc.setSource( |
| 139 | + android.getSourceSets().getByName("main").getJava().getSrcDirs()); |
| 140 | + } |
| 141 | + android |
| 142 | + .getLibraryVariants() |
| 143 | + .all( |
| 144 | + variant -> { |
| 145 | + if (!"release".equals(variant.getName().toLowerCase())) { |
| 146 | + return; |
| 147 | + } |
| 148 | + javadoc.setClasspath( |
| 149 | + javadoc |
| 150 | + .getClasspath() |
| 151 | + .plus(getJars(variant.getCompileConfiguration()) |
| 152 | + .plus(getJars(variant.getRuntimeConfiguration())))); |
| 153 | + |
| 154 | + // this includes compiled sources which avoids "cannot find symbol" errors |
| 155 | + javadoc.setClasspath( |
| 156 | + javadoc |
| 157 | + .getClasspath() |
| 158 | + .plus( |
| 159 | + project.files(variant.getJavaCompile().getDestinationDir()))); |
| 160 | + }); |
| 161 | + } else { |
| 162 | + JavaPluginConvention java = |
| 163 | + project.getConvention().getPlugin(JavaPluginConvention.class); |
| 164 | + javadoc.setSource(java.getSourceSets().getByName("main").getAllJava()); |
| 165 | + javadoc.setClasspath(java.getSourceSets().getByName("main").getCompileClasspath()); |
| 166 | + } |
| 167 | + |
| 168 | + Configuration javadocClasspath = |
| 169 | + project.getConfigurations().findByName("javadocClasspath"); |
| 170 | + |
| 171 | + if (javadocClasspath != null) { |
| 172 | + javadoc.setClasspath(javadoc.getClasspath().plus(getJars(javadocClasspath))); |
| 173 | + } |
| 174 | + |
| 175 | + // Gradle passes the (unsupported) -doctitle option to the doclava doclet. |
| 176 | + // We set the title to null to overcome this issue |
| 177 | + javadoc.setTitle(null); |
| 178 | + javadoc.getOptions().setDoclet("com.google.doclava.Doclava"); |
| 179 | + |
| 180 | + // set book path and project path used in g3 templates |
| 181 | + CoreJavadocOptions options = (CoreJavadocOptions) javadoc.getOptions(); |
| 182 | + options |
| 183 | + .addMultilineMultiValueOption("hdf") |
| 184 | + .setValue( |
| 185 | + ImmutableList.of( |
| 186 | + ImmutableList.of("book.path", "/docs/reference/_book.yaml"), |
| 187 | + ImmutableList.of("project.path", "/_project.yaml"))); |
| 188 | + |
| 189 | + // root path assumed by docs |
| 190 | + options.addStringOption("toroot", "/docs/reference/android/"); |
| 191 | + |
| 192 | + // TODO(ashwinraghav) : These currently fail because of unknown annotations in |
| 193 | + // Firestore |
| 194 | + // @Documented, @TypeQualifierNickname, @Retention which are relatively minor |
| 195 | + // b/74115412 |
| 196 | + // options.addMultilineStringsOption("error").setValue(["103", "104"]) |
| 197 | + |
| 198 | + options.addMultilineStringsOption("warning").setValue(ImmutableList.of("101", "106")); |
| 199 | + |
| 200 | + // destination for generated toc yaml |
| 201 | + options.addStringOption("yaml", "_toc.yaml"); |
| 202 | + |
| 203 | + if (project.hasProperty("templatedir")) { |
| 204 | + options.addStringOption( |
| 205 | + "templatedir", project.getProperties().get("templatedir").toString()); |
| 206 | + } |
| 207 | + |
| 208 | + // Custom doclet can be specified in certain scenarios |
| 209 | + if (project.hasProperty("docletpath")) { |
| 210 | + options.setDocletpath( |
| 211 | + ImmutableList.of(project.file(project.getProperties().get("docletpath")))); |
| 212 | + } else { |
| 213 | + options.setDocletpath( |
| 214 | + ImmutableList.copyOf( |
| 215 | + project.getConfigurations().getByName("javadocCustomConfig").getFiles())); |
| 216 | + } |
| 217 | + |
| 218 | + ImmutableList.Builder<List<String>> federationApiFiles = ImmutableList.builder(); |
| 219 | + ImmutableList.Builder<List<String>> federationUrls = ImmutableList.builder(); |
| 220 | + |
| 221 | + if (project.hasProperty("android_api_file")) { |
| 222 | + federationUrls.add(ImmutableList.of("Android", "https://developer.android.com")); |
| 223 | + federationApiFiles.add( |
| 224 | + ImmutableList.of( |
| 225 | + "Android", project.getProperties().get("android_api_file").toString())); |
| 226 | + } |
| 227 | + if (project.hasProperty("android_support_library_api_file")) { |
| 228 | + federationUrls.add( |
| 229 | + ImmutableList.of("Android Support Library", "https://developer.android.com")); |
| 230 | + federationApiFiles.add( |
| 231 | + ImmutableList.of( |
| 232 | + "Android Support Library", |
| 233 | + project |
| 234 | + .getProperties() |
| 235 | + .get("android_support_library_api_file") |
| 236 | + .toString())); |
| 237 | + } |
| 238 | + if (project.hasProperty("google_play_services_api_file")) { |
| 239 | + federationUrls.add( |
| 240 | + ImmutableList.of( |
| 241 | + "Google Play services", "https://developers.google.com/android")); |
| 242 | + federationApiFiles.add( |
| 243 | + ImmutableList.of( |
| 244 | + "Google Play services", |
| 245 | + project.getProperties().get("google_play_services_api_file").toString())); |
| 246 | + } |
| 247 | + if (project.hasProperty("tasks_api_file")) { |
| 248 | + federationUrls.add( |
| 249 | + ImmutableList.of("Tasks", "https://developers.google.com/android")); |
| 250 | + federationApiFiles.add( |
| 251 | + ImmutableList.of( |
| 252 | + "Tasks", project.getProperties().get("tasks_api_file").toString())); |
| 253 | + } |
| 254 | + |
| 255 | + // set federated links for external projects that need to be linked |
| 256 | + options.addMultilineMultiValueOption("federate").setValue(federationUrls.build()); |
| 257 | + options |
| 258 | + .addMultilineMultiValueOption("federationapi") |
| 259 | + .setValue(federationApiFiles.build()); |
| 260 | + })); |
| 261 | + } |
| 262 | + |
| 263 | + private static void applyDokka(Project project) { |
| 264 | + project.apply(ImmutableMap.of("plugin", DokkaAndroidPlugin.class)); |
| 265 | + DokkaTask dokka = (DokkaTask) project.getTasks().getByName("dokka"); |
| 266 | + dokka.setOutputDirectory(project.getBuildDir() + "/docs/javadoc/reference"); |
| 267 | + applyDummyJavadoc(project).dependsOn(dokka); |
| 268 | + } |
| 269 | + |
| 270 | + private static Task applyDummyJavadoc(Project project) { |
| 271 | + return project |
| 272 | + .getTasks() |
| 273 | + .create(TasksKt.JAVADOC_TASK_NAME, task -> { |
| 274 | + task.doLast( |
| 275 | + t -> { |
| 276 | + File dir = project.file(project.getBuildDir() + "/tmp/javadoc"); |
| 277 | + project.mkdir(dir); |
| 278 | + try { |
| 279 | + project.file(dir + "/api.txt").createNewFile(); |
| 280 | + } catch (IOException e) { |
| 281 | + throw new GradleException("Unable to create file", e); |
| 282 | + } |
| 283 | + }); |
| 284 | + task.doLast( |
| 285 | + t -> project.mkdir(project.getBuildDir() + "/docs/javadoc/reference")); |
| 286 | + }); |
| 287 | + } |
| 288 | + |
| 289 | + private static FileCollection getJars(Configuration configuration) { |
| 290 | + return configuration |
| 291 | + .getIncoming() |
| 292 | + .artifactView( |
| 293 | + view -> |
| 294 | + view.attributes( |
| 295 | + attrs -> attrs.attribute(Attribute.of("artifactType", String.class), "jar"))) |
| 296 | + .getArtifacts() |
| 297 | + .getArtifactFiles(); |
| 298 | + } |
| 299 | +} |
0 commit comments