1// Copyright (C) 2019 The Android Open Source Project
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
15// How API docs are generated:
16//
17// raw source files --(metalava)--> stub source files --(doclava)--> API doc
18//
19// The metalava conversion is done by droidstub modules framework-doc-*-stubs.
20// The API doc generation is done by the various droiddoc modules each of which
21// is for different format.
22
23// These defaults enable doc-stub generation, api lint database generation and sdk value generation.
24stubs_defaults {
25    name: "android-non-updatable-doc-stubs-defaults",
26    defaults: ["android-non-updatable-stubs-defaults"],
27    srcs: [
28        // No longer part of the stubs, but are included in the docs.
29        ":android-test-base-sources",
30        ":android-test-mock-sources",
31        ":android-test-runner-sources",
32    ],
33    flags: [
34        // These errors are suppressed in the doc stubs as it isn't easy to suppress them.
35        // They remain unsuppressed/active in the "main" stubs build (the jar stubs).
36        // These can be removed when either a) all the issues have been fixed or
37        // b) these reporting of these issues is gated behind api lint being enabled in metalava.
38        "--hide BroadcastBehavior",
39        "--hide DeprecationMismatch",
40        "--hide MissingPermission",
41        "--hide RequiresPermission",
42        "--hide SdkConstant",
43        "--hide Todo",
44    ],
45    create_doc_stubs: true,
46    write_sdk_values: true,
47}
48
49// Defaults module for doc-stubs targets that use module source code as input.
50stubs_defaults {
51    name: "framework-doc-stubs-sources-default",
52    defaults: ["android-non-updatable-doc-stubs-defaults"],
53    srcs: [
54        ":art.module.public.api{.public.stubs.source}",
55        ":conscrypt.module.public.api{.public.stubs.source}",
56        ":i18n.module.public.api{.public.stubs.source}",
57
58        ":framework-adservices-sources",
59        ":framework-appsearch-sources",
60        ":framework-connectivity-sources",
61        ":framework-bluetooth-sources",
62        ":framework-connectivity-tiramisu-updatable-sources",
63        ":framework-graphics-srcs",
64        ":framework-mediaprovider-sources",
65        ":framework-nearby-sources",
66        ":framework-nfc-updatable-sources",
67        ":framework-ondevicepersonalization-sources",
68        ":framework-permission-sources",
69        ":framework-permission-s-sources",
70        ":framework-profiling-sources",
71        ":framework-scheduling-sources",
72        ":framework-sdkextensions-sources",
73        ":framework-statsd-sources",
74        ":framework-sdksandbox-sources",
75        ":framework-tethering-srcs",
76        ":framework-uwb-updatable-sources",
77        ":framework-wifi-updatable-sources",
78        ":ike-srcs",
79        ":updatable-media-srcs",
80    ],
81}
82
83droidstubs {
84    name: "android-non-updatable-doc-stubs",
85    defaults: [
86        "android-non-updatable-doc-stubs-defaults",
87        "module-classpath-stubs-defaults",
88    ],
89}
90
91droidstubs {
92    name: "android-non-updatable-doc-stubs-system",
93    defaults: [
94        "android-non-updatable-doc-stubs-defaults",
95        "module-classpath-stubs-defaults",
96    ],
97    flags: ["--show-annotation android.annotation.SystemApi\\(client=android.annotation.SystemApi.Client.PRIVILEGED_APPS\\)"],
98}
99
100droidstubs {
101    name: "android-non-updatable-doc-stubs-module-lib",
102    defaults: [
103        "android-non-updatable-doc-stubs-defaults",
104        "module-classpath-stubs-defaults",
105    ],
106    flags: [
107        "--show-annotation android.annotation.SystemApi\\(client=android.annotation.SystemApi.Client.PRIVILEGED_APPS\\)",
108        "--show-annotation android.annotation.SystemApi\\(client=android.annotation.SystemApi.Client.MODULE_LIBRARIES\\)",
109    ],
110    generate_stubs: false, // We're only using this module for the annotations.zip output, disable doc-stubs.
111    write_sdk_values: false,
112}
113
114droidstubs {
115    name: "android-non-updatable-doc-stubs-system-server",
116    defaults: [
117        "android-non-updatable-doc-stubs-defaults",
118        "module-classpath-stubs-defaults",
119    ],
120    flags: [
121        "--show-annotation android.annotation.SystemApi\\(client=android.annotation.SystemApi.Client.PRIVILEGED_APPS\\)",
122        "--show-annotation android.annotation.SystemApi\\(client=android.annotation.SystemApi.Client.MODULE_LIBRARIES\\)",
123        "--show-annotation android.annotation.SystemApi\\(client=android.annotation.SystemApi.Client.SYSTEM_SERVER\\)",
124    ],
125    generate_stubs: false, // We're only using this module for the annotations.zip output, disable doc-stubs.
126    write_sdk_values: false,
127}
128
129droidstubs {
130    name: "framework-doc-stubs",
131    defaults: ["android-non-updatable-doc-stubs-defaults"],
132    srcs: [":all-modules-public-stubs-source"],
133    api_levels_module: "api_versions_public",
134    aidl: {
135        include_dirs: [
136            "packages/modules/Connectivity/framework/aidl-export",
137            "packages/modules/Media/apex/aidl/stable",
138        ],
139    },
140}
141
142droidstubs {
143    name: "framework-doc-system-stubs",
144    defaults: ["framework-doc-stubs-sources-default"],
145    flags: ["--show-annotation android.annotation.SystemApi\\(client=android.annotation.SystemApi.Client.PRIVILEGED_APPS\\)"],
146    api_levels_module: "api_versions_system",
147}
148
149/////////////////////////////////////////////////////////////////////
150// API docs are created from the generated stub source files
151// using droiddoc
152/////////////////////////////////////////////////////////////////////
153
154doc_defaults {
155    name: "framework-docs-default",
156    sdk_version: "none",
157    system_modules: "none",
158    libs: [
159        "stub-annotations",
160        "unsupportedappusage",
161    ],
162    html_dirs: [
163        "docs/html",
164    ],
165    knowntags: [
166        "docs/knowntags.txt",
167        ":art.module.public.api{.doctags}",
168    ],
169    custom_template: "droiddoc-templates-sdk",
170    resourcesdir: "docs/html/reference/images/",
171    resourcesoutdir: "reference/android/images/",
172    lint_baseline: "javadoc-lint-baseline",
173    flags: [
174        "-android",
175        "-manifest $(location :frameworks-base-core-AndroidManifest.xml)",
176        "-metalavaApiSince",
177        "-werror",
178        "-lerror",
179        "-overview $(location :frameworks-base-java-overview)",
180        // Federate Support Library references against local API file.
181        "-federate SupportLib https://developer.android.com",
182        "-federationapi SupportLib $(location :current-support-api)",
183        // Federate Support Library references against local API file.
184        "-federate AndroidX https://developer.android.com",
185        "-federationapi AndroidX $(location :current-androidx-api)",
186        // doclava contains checks for a few issues that are have been migrated to metalava.
187        // disable them in doclava, to avoid mistriggering or double triggering.
188        "-hide 101", // TODO: turn Lint 101 back into an error again
189        "-hide 111", // HIDDEN_SUPERCLASS
190        "-hide 113", // DEPRECATION_MISMATCH
191        "-hide 125", // REQUIRES_PERMISSION
192        "-hide 126", // BROADCAST_BEHAVIOR
193        "-hide 127", // SDK_CONSTANT
194        "-hide 128", // TODO
195    ],
196    hdf: [
197        "dac true",
198        "sdk.codename O",
199        "sdk.preview.version 1",
200        "sdk.version 7.0",
201        "sdk.rel.id 1",
202        "sdk.preview 0",
203    ],
204    arg_files: [
205        ":frameworks-base-core-AndroidManifest.xml",
206        ":frameworks-base-java-overview",
207        ":current-support-api",
208        ":current-androidx-api",
209    ],
210    // TODO(b/169090544): remove below aidl includes.
211    aidl: {
212        include_dirs: [
213            "frameworks/av/aidl",
214            "frameworks/base/media/aidl",
215            "frameworks/native/libs/permission/aidl",
216        ],
217    },
218}
219
220droiddoc {
221    name: "offline-sdk-docs",
222    defaults: ["framework-docs-default"],
223    srcs: [
224        ":framework-doc-stubs{.exportable}",
225    ],
226    hdf: [
227        "android.whichdoc offline",
228    ],
229    compat_config: ":global-compat-config",
230    proofread_file: "offline-sdk-docs-proofread.txt",
231    flags: [
232        "-offlinemode",
233        "-title \"Android SDK\"",
234    ],
235    static_doc_index_redirect: "docs/docs-preview-index.html",
236}
237
238droiddoc {
239    // Please sync with android-api-council@ before making any changes for the name property below.
240    // Since there's cron jobs that fetch offline-sdk-referenceonly-docs-docs.zip periodically.
241    // See b/116221385 for reference.
242    name: "offline-sdk-referenceonly-docs",
243    defaults: ["framework-docs-default"],
244    srcs: [
245        ":framework-doc-stubs{.exportable}",
246    ],
247    hdf: [
248        "android.whichdoc offline",
249    ],
250    proofread_file: "offline-sdk-referenceonly-docs-proofread.txt",
251    flags: [
252        "-offlinemode",
253        "-title \"Android SDK\"",
254        "-referenceonly",
255    ],
256    static_doc_index_redirect: "docs/docs-documentation-redirect.html",
257    static_doc_properties: "docs/source.properties",
258}
259
260droiddoc {
261    // Please sync with android-api-council@ before making any changes for the name property below.
262    // Since there's cron jobs that fetch offline-system-sdk-referenceonly-docs-docs.zip periodically.
263    // See b/116221385 for reference.
264    name: "offline-system-sdk-referenceonly-docs",
265    defaults: ["framework-docs-default"],
266    srcs: [
267        ":framework-doc-system-stubs",
268    ],
269    hdf: [
270        "android.whichdoc offline",
271    ],
272    proofread_file: "offline-system-sdk-referenceonly-docs-proofread.txt",
273    flags: [
274        "-hide 101",
275        "-hide 104",
276        "-hide 108",
277        "-offlinemode",
278        "-title \"Android System SDK\"",
279        "-referenceonly",
280    ],
281    static_doc_index_redirect: "docs/docs-documentation-redirect.html",
282    static_doc_properties: "docs/source.properties",
283}
284
285droiddoc {
286    name: "ds-docs-java",
287    defaults: ["framework-docs-default"],
288    srcs: [
289        ":framework-doc-stubs{.exportable}",
290    ],
291    hdf: [
292        "android.whichdoc online",
293        "android.hasSamples true",
294    ],
295    proofread_file: "ds-docs-proofread.txt",
296    flags: [
297        " -toroot /",
298        "-yamlV2",
299        "-samplegroup Admin",
300        "-samplegroup Background",
301        "-samplegroup Connectivity",
302        "-samplegroup Content",
303        "-samplegroup Input",
304        "-samplegroup Media",
305        "-samplegroup Notification",
306        "-samplegroup RenderScript",
307        "-samplegroup Security",
308        "-samplegroup Sensors",
309        "-samplegroup System",
310        "-samplegroup Testing",
311        "-samplegroup UI",
312        "-samplegroup Views",
313        "-samplegroup Wearable",
314        "-devsite",
315        "-samplesdir",
316        "development/samples/browseable",
317    ],
318}
319
320droiddoc {
321    name: "ds-docs-kt",
322    srcs: [
323        ":framework-doc-stubs{.exportable}",
324    ],
325    flags: [
326        "-noJdkLink",
327        "-links https://kotlinlang.org/api/latest/jvm/stdlib/^external/dokka/package-list",
328        "-noStdlibLink",
329    ],
330    proofread_file: "ds-dokka-proofread.txt",
331    dokka_enabled: true,
332}
333
334java_genrule {
335    name: "ds-docs",
336    tools: [
337        "zip2zip",
338        "merge_zips",
339    ],
340    srcs: [
341        ":ds-docs-java{.docs.zip}",
342        ":ds-docs-kt{.docs.zip}",
343    ],
344    out: ["ds-docs.zip"],
345    dist: {
346        targets: ["docs"],
347    },
348    cmd: "$(location zip2zip) -i $(location :ds-docs-kt{.docs.zip}) -o $(genDir)/ds-docs-kt-moved.zip **/*:en/reference/kotlin && " +
349        "$(location merge_zips) $(out) $(location :ds-docs-java{.docs.zip}) $(genDir)/ds-docs-kt-moved.zip",
350}
351
352java_genrule {
353    name: "ds-docs-switched",
354    tools: [
355        "switcher4",
356        "soong_zip",
357    ],
358    srcs: [
359        ":ds-docs-java{.docs.zip}",
360        ":ds-docs-kt{.docs.zip}",
361    ],
362    out: ["ds-docs-switched.zip"],
363    dist: {
364        targets: ["docs"],
365    },
366    cmd: "unzip -q $(location :ds-docs-java{.docs.zip}) -d $(genDir) && " +
367        "unzip -q $(location :ds-docs-kt{.docs.zip}) -d $(genDir)/en/reference/kotlin && " +
368        "SWITCHER=$$(cd $$(dirname $(location switcher4)) && pwd)/$$(basename $(location switcher4)) && " +
369        "(cd $(genDir)/en/reference && $$SWITCHER --work platform) > /dev/null && " +
370        "$(location soong_zip) -o $(out) -C $(genDir) -D $(genDir)",
371}
372
373droiddoc {
374    name: "ds-static-docs",
375    defaults: ["framework-docs-default"],
376    srcs: [
377        ":framework-doc-stubs{.exportable}",
378    ],
379    hdf: [
380        "android.whichdoc online",
381    ],
382    flags: [
383        "-staticonly",
384        "-toroot /",
385        "-devsite",
386        "-ignoreJdLinks",
387    ],
388}
389
390droiddoc {
391    name: "ds-ref-navtree-docs",
392    defaults: ["framework-docs-default"],
393    srcs: [
394        ":framework-doc-stubs{.exportable}",
395    ],
396    hdf: [
397        "android.whichdoc online",
398    ],
399    flags: [
400        "-toroot /",
401        "-atLinksNavtree",
402        "-navtreeonly",
403    ],
404}
405