Skip to content

Commit 3f4b32d

Browse files
vkryachkovkryachko
authored
Improve kotlindoc rendering. (#1777)
Specifically allows SDKs to declare dependencies via `javadocClasspath` configuration for the dokka run to make `{@link}` tags render properly. Depends on https://android-review.googlesource.com/c/platform/external/dokka/+/1365296 for rendering to work correctly.
1 parent 37dd2b1 commit 3f4b32d

File tree

4 files changed

+89
-72
lines changed

4 files changed

+89
-72
lines changed

‎buildSrc/src/main/java/com/google/firebase/gradle/plugins/Dokka.java

Lines changed: 82 additions & 70 deletions
Original file line numberDiff line numberDiff line change
@@ -14,6 +14,7 @@
1414

1515
package com.google.firebase.gradle.plugins;
1616

17+
import com.android.build.api.attributes.BuildTypeAttr;
1718
import com.android.build.gradle.LibraryExtension;
1819
import com.google.common.collect.ImmutableMap;
1920
import com.sun.istack.Nullable;
@@ -24,6 +25,7 @@
2425
import java.util.Optional;
2526
import org.gradle.api.GradleException;
2627
import org.gradle.api.Project;
28+
import org.gradle.api.artifacts.Configuration;
2729
import org.gradle.api.attributes.Attribute;
2830
import org.gradle.api.file.FileCollection;
2931
import org.gradle.api.file.RelativePath;
@@ -53,83 +55,93 @@ static void configure(
5355
@Nullable LibraryExtension android,
5456
FirebaseLibraryExtension firebaseLibrary) {
5557

56-
String dokkaPluginName =
57-
android == null ? "org.jetbrains.dokka" : "org.jetbrains.dokka-android";
58-
project.apply(ImmutableMap.of("plugin", dokkaPluginName));
58+
Configuration javadocClasspath = project.getConfigurations().create("javadocClasspath");
59+
javadocClasspath
60+
.getAttributes()
61+
.attribute(
62+
BuildTypeAttr.ATTRIBUTE, project.getObjects().named(BuildTypeAttr.class, "release"));
5963

60-
if (!firebaseLibrary.publishJavadoc) {
61-
project.getTasks().register("kotlindoc");
62-
return;
63-
}
64-
Class<? extends DokkaTask> taskClass =
65-
android == null ? DokkaTask.class : DokkaAndroidTask.class;
66-
DokkaTask dokkaTask = configure(project, taskClass);
67-
68-
if (dokkaTask instanceof DokkaAndroidTask) {
69-
((DokkaAndroidTask) dokkaTask).setNoAndroidSdkLink(true);
70-
71-
android
72-
.getLibraryVariants()
73-
.all(
74-
v -> {
75-
if (v.getName().equals("release")) {
76-
project.afterEvaluate(
77-
p -> {
64+
project.afterEvaluate(
65+
p -> {
66+
String dokkaPluginName =
67+
android == null ? "org.jetbrains.dokka" : "org.jetbrains.dokka-android";
68+
project.apply(ImmutableMap.of("plugin", dokkaPluginName));
69+
70+
if (!firebaseLibrary.publishJavadoc) {
71+
project.getTasks().register("kotlindoc");
72+
return;
73+
}
74+
Class<? extends DokkaTask> taskClass =
75+
android == null ? DokkaTask.class : DokkaAndroidTask.class;
76+
DokkaTask dokkaTask = configure(project, taskClass);
77+
78+
if (dokkaTask instanceof DokkaAndroidTask) {
79+
((DokkaAndroidTask) dokkaTask).setNoAndroidSdkLink(true);
80+
81+
android
82+
.getLibraryVariants()
83+
.all(
84+
v -> {
85+
if (v.getName().equals("release")) {
7886
FileCollection artifactFiles =
79-
v.getRuntimeConfiguration()
80-
.getIncoming()
81-
.artifactView(
82-
view -> {
83-
view.attributes(
84-
attrs ->
85-
attrs.attribute(
86-
Attribute.of("artifactType", String.class),
87-
"jar"));
88-
view.componentFilter(
89-
c ->
90-
!c.getDisplayName()
91-
.startsWith("androidx.annotation:annotation:"));
92-
})
93-
.getArtifacts()
94-
.getArtifactFiles()
87+
getJars(v.getRuntimeConfiguration())
88+
.plus(getJars(javadocClasspath))
9589
.plus(project.files(android.getBootClasspath()));
9690
dokkaTask.setClasspath(artifactFiles);
97-
});
98-
}
99-
});
100-
}
91+
}
92+
});
93+
}
10194

102-
project
103-
.getTasks()
104-
.create(
105-
"kotlindoc",
106-
Copy.class,
107-
copy -> {
108-
copy.dependsOn(dokkaTask);
109-
copy.setDestinationDir(
110-
project.file(project.getRootProject().getBuildDir() + "/firebase-kotlindoc"));
111-
copy.from(
112-
project.getBuildDir() + "/dokka/firebase",
113-
cfg -> {
114-
cfg.exclude("package-list");
115-
cfg.filesMatching(
116-
"_toc.yaml",
117-
fileCopy -> {
118-
fileCopy.setRelativePath(
119-
new RelativePath(
120-
true, "client", firebaseLibrary.artifactId.get(), "_toc.yaml"));
121-
fileCopy.filter(
122-
line ->
123-
line.replaceFirst(
124-
"\\spath:\\s/", " path: /docs/reference/kotlin/"));
95+
project
96+
.getTasks()
97+
.create(
98+
"kotlindoc",
99+
Copy.class,
100+
copy -> {
101+
copy.dependsOn(dokkaTask);
102+
copy.setDestinationDir(
103+
project.file(
104+
project.getRootProject().getBuildDir() + "/firebase-kotlindoc"));
105+
copy.from(
106+
project.getBuildDir() + "/dokka/firebase",
107+
cfg -> {
108+
cfg.exclude("package-list");
109+
cfg.filesMatching(
110+
"_toc.yaml",
111+
fileCopy -> {
112+
fileCopy.setRelativePath(
113+
new RelativePath(
114+
true,
115+
"client",
116+
firebaseLibrary.artifactId.get(),
117+
"_toc.yaml"));
118+
fileCopy.filter(
119+
line ->
120+
line.replaceFirst(
121+
"\\spath:\\s/", " path: /docs/reference/kotlin/"));
122+
});
123+
cfg.filesMatching(
124+
"**/*.html",
125+
fileCopy ->
126+
fileCopy.filter(
127+
line -> line.replaceAll("https://firebase.google.com", "")));
125128
});
126-
cfg.filesMatching(
127-
"**/*.html",
128-
fileCopy ->
129-
fileCopy.filter(
130-
line -> line.replaceAll("https://firebase.google.com", "")));
131129
});
132-
});
130+
});
131+
}
132+
133+
private static FileCollection getJars(Configuration configuration) {
134+
return configuration
135+
.getIncoming()
136+
.artifactView(
137+
view -> {
138+
view.attributes(
139+
attrs -> attrs.attribute(Attribute.of("artifactType", String.class), "jar"));
140+
view.componentFilter(
141+
c -> !c.getDisplayName().startsWith("androidx.annotation:annotation:"));
142+
})
143+
.getArtifacts()
144+
.getArtifactFiles();
133145
}
134146

135147
static <T extends DokkaTask> T configure(Project project, Class<T> taskType) {

‎buildSrc/src/main/java/com/google/firebase/gradle/plugins/FirebaseLibraryPlugin.java

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -102,7 +102,8 @@ public void apply(Project project) {
102102
.setFreeCompilerArgs(
103103
ImmutableList.of("-module-name", kotlinModuleName(project))));
104104

105-
project.afterEvaluate(p -> Dokka.configure(project, android, firebaseLibrary));
105+
106+
Dokka.configure(project, android, firebaseLibrary);
106107
}
107108

108109
private static void setupApiInformationAnalysis(Project project, LibraryExtension android) {

‎firebase-common/firebase-common.gradle

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -66,6 +66,9 @@ dependencies {
6666
implementation 'com.google.android.gms:play-services-basement:17.0.0'
6767
implementation "com.google.android.gms:play-services-tasks:17.0.0"
6868

69+
// FirebaseApp references storage, so storage needs to be on classpath when dokka runs.
70+
javadocClasspath project(path: ':firebase-storage')
71+
6972
compileOnly 'com.google.auto.value:auto-value-annotations:1.6.6'
7073
compileOnly 'com.google.code.findbugs:jsr305:3.0.2'
7174

‎kotlindoc/package-lists/firebase/package-list

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -41,6 +41,7 @@ com.google.firebase.inappmessaging.display
4141
com.google.firebase.inappmessaging.display.ktx
4242
com.google.firebase.inappmessaging.ktx
4343
com.google.firebase.inappmessaging.model
44+
com.google.firebase.installations
4445
com.google.firebase.ktx
4546
com.google.firebase.messaging
4647
com.google.firebase.ml.common
@@ -73,4 +74,4 @@ com.google.firebase.remoteconfig.ktx
7374
com.google.firebase.storage
7475
com.google.firebase.storage.ktx
7576
io.fabric.sdk.android.fabric
76-
io.fabric.sdk.android.fabric.services.concurrency
77+
io.fabric.sdk.android.fabric.services.concurrency

0 commit comments

Comments
 (0)