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