api/ApiDocs.bp

// Copyright (C) 2019 The Android Open Source Project
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
//      http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.

// How API docs are generated:
//
// raw source files --(metalava)--> stub source files --(doclava)--> API doc
//
// The metalava conversion is done by droidstub modules framework-doc-*-stubs.
// The API doc generation is done by the various droiddoc modules each of which
// is for different format.

// These defaults enable doc-stub generation, api lint database generation and sdk value generation.
stubs_defaults {
    name: "android-non-updatable-doc-stubs-defaults",
    defaults: ["android-non-updatable-stubs-defaults"],
    srcs: [
        // No longer part of the stubs, but are included in the docs.
        ":android-test-base-sources",
        ":android-test-mock-sources",
        ":android-test-runner-sources",
    ],
    flags: [
        // These errors are suppressed in the doc stubs as it isn't easy to suppress them.
        // They remain unsuppressed/active in the "main" stubs build (the jar stubs).
        // These can be removed when either a) all the issues have been fixed or
        // b) these reporting of these issues is gated behind api lint being enabled in metalava.
        "--hide BroadcastBehavior",
        "--hide DeprecationMismatch",
        "--hide MissingPermission",
        "--hide RequiresPermission",
        "--hide SdkConstant",
        "--hide Todo",
    ],
    create_doc_stubs: true,
    write_sdk_values: true,
}

// Defaults module for doc-stubs targets that use module source code as input.
stubs_defaults {
    name: "framework-doc-stubs-sources-default",
    defaults: ["android-non-updatable-doc-stubs-defaults"],
    srcs: [
        ":art.module.public.api{.public.stubs.source}",
        ":conscrypt.module.public.api{.public.stubs.source}",
        ":i18n.module.public.api{.public.stubs.source}",

        ":framework-adservices-sources",
        ":framework-appsearch-sources",
        ":framework-connectivity-sources",
        ":framework-bluetooth-sources",
        ":framework-connectivity-tiramisu-updatable-sources",
        ":framework-graphics-srcs",
        ":framework-mediaprovider-sources",
        ":framework-nearby-sources",
        ":framework-nfc-updatable-sources",
        ":framework-ondevicepersonalization-sources",
        ":framework-permission-sources",
        ":framework-permission-s-sources",
        ":framework-profiling-sources",
        ":framework-scheduling-sources",
        ":framework-sdkextensions-sources",
        ":framework-statsd-sources",
        ":framework-sdksandbox-sources",
        ":framework-tethering-srcs",
        ":framework-uwb-updatable-sources",
        ":framework-wifi-updatable-sources",
        ":ike-srcs",
        ":updatable-media-srcs",
    ],
}

droidstubs {
    name: "android-non-updatable-doc-stubs",
    defaults: [
        "android-non-updatable-doc-stubs-defaults",
        "module-classpath-stubs-defaults",
    ],
}

droidstubs {
    name: "android-non-updatable-doc-stubs-system",
    defaults: [
        "android-non-updatable-doc-stubs-defaults",
        "module-classpath-stubs-defaults",
    ],
    flags: ["--show-annotation android.annotation.SystemApi\\(client=android.annotation.SystemApi.Client.PRIVILEGED_APPS\\)"],
}

droidstubs {
    name: "android-non-updatable-doc-stubs-module-lib",
    defaults: [
        "android-non-updatable-doc-stubs-defaults",
        "module-classpath-stubs-defaults",
    ],
    flags: [
        "--show-annotation android.annotation.SystemApi\\(client=android.annotation.SystemApi.Client.PRIVILEGED_APPS\\)",
        "--show-annotation android.annotation.SystemApi\\(client=android.annotation.SystemApi.Client.MODULE_LIBRARIES\\)",
    ],
    generate_stubs: false, // We're only using this module for the annotations.zip output, disable doc-stubs.
    write_sdk_values: false,
}

droidstubs {
    name: "android-non-updatable-doc-stubs-system-server",
    defaults: [
        "android-non-updatable-doc-stubs-defaults",
        "module-classpath-stubs-defaults",
    ],
    flags: [
        "--show-annotation android.annotation.SystemApi\\(client=android.annotation.SystemApi.Client.PRIVILEGED_APPS\\)",
        "--show-annotation android.annotation.SystemApi\\(client=android.annotation.SystemApi.Client.MODULE_LIBRARIES\\)",
        "--show-annotation android.annotation.SystemApi\\(client=android.annotation.SystemApi.Client.SYSTEM_SERVER\\)",
    ],
    generate_stubs: false, // We're only using this module for the annotations.zip output, disable doc-stubs.
    write_sdk_values: false,
}

droidstubs {
    name: "framework-doc-stubs",
    defaults: ["android-non-updatable-doc-stubs-defaults"],
    flags: [
        // Ignore any compatibility errors, see check_api.last_released below for more information.
        "--hide-category Compatibility",
    ],
    srcs: [":all-modules-public-stubs-source-exportable"],
    api_levels_module: "api_versions_public",
    aidl: {
        include_dirs: [
            "packages/modules/Connectivity/framework/aidl-export",
            "packages/modules/Media/apex/aidl/stable",
        ],
    },

    // Pass the previously released API to support reverting flagged APIs. Without this, reverting
    // a flagged API will cause it to be removed, even if it had previously been released. This
    // has the side effect of causing compatibility issues to be reported but they are already
    // checked elsewhere so they will be ignored, see `--hide-category Compatibility` above.
    check_api: {
        last_released: {
            api_file: ":android.api.combined.public.latest",
            removed_api_file: ":android-removed.api.combined.public.latest",
        },
    },
}

droidstubs {
    name: "framework-doc-system-stubs",
    defaults: ["framework-doc-stubs-sources-default"],
    flags: [
        "--show-annotation android.annotation.SystemApi\\(client=android.annotation.SystemApi.Client.PRIVILEGED_APPS\\)",
        // Ignore any compatibility errors, see check_api.last_released below for more information.
        "--hide-category Compatibility",
    ],
    api_levels_module: "api_versions_system",

    // Pass the previously released API to support reverting flagged APIs. Without this, reverting
    // a flagged API will cause it to be removed, even if it had previously been released. This
    // has the side effect of causing compatibility issues to be reported but they are already
    // checked elsewhere so they will be ignored, see `--hide-category Compatibility` above.
    check_api: {
        last_released: {
            api_file: ":android.api.combined.system.latest",
            removed_api_file: ":android-removed.api.combined.system.latest",
        },
    },
}

/////////////////////////////////////////////////////////////////////
// API docs are created from the generated stub source files
// using droiddoc
/////////////////////////////////////////////////////////////////////

doc_defaults {
    name: "framework-docs-default",
    sdk_version: "none",
    system_modules: "none",
    libs: [
        "stub-annotations",
        "unsupportedappusage",
    ],
    html_dirs: [
        "docs/html",
    ],
    knowntags: [
        "docs/knowntags.txt",
        ":art.module.public.api{.doctags}",
    ],
    custom_template: "droiddoc-templates-sdk",
    resourcesdir: "docs/html/reference/images/",
    resourcesoutdir: "reference/android/images/",
    lint_baseline: "javadoc-lint-baseline",
    flags: [
        "-android",
        "-manifest $(location :frameworks-base-core-AndroidManifest.xml)",
        "-metalavaApiSince",
        "-werror",
        "-lerror",
        "-overview $(location :frameworks-base-java-overview)",
        // Federate Support Library references against local API file.
        "-federate SupportLib https://developer.android.com",
        "-federationapi SupportLib $(location :current-support-api)",
        // Federate Support Library references against local API file.
        "-federate AndroidX https://developer.android.com",
        "-federationapi AndroidX $(location :current-androidx-api)",
        // doclava contains checks for a few issues that are have been migrated to metalava.
        // disable them in doclava, to avoid mistriggering or double triggering.
        "-hide 101", // TODO: turn Lint 101 back into an error again
        "-hide 111", // HIDDEN_SUPERCLASS
        "-hide 113", // DEPRECATION_MISMATCH
        "-hide 125", // REQUIRES_PERMISSION
        "-hide 126", // BROADCAST_BEHAVIOR
        "-hide 127", // SDK_CONSTANT
        "-hide 128", // TODO
    ],
    hdf: [
        "dac true",
        "sdk.codename O",
        "sdk.preview.version 1",
        "sdk.version 7.0",
        "sdk.rel.id 1",
        "sdk.preview 0",
    ],
    arg_files: [
        ":frameworks-base-core-AndroidManifest.xml",
        ":frameworks-base-java-overview",
        ":current-support-api",
        ":current-androidx-api",
    ],
    // TODO(b/169090544): remove below aidl includes.
    aidl: {
        include_dirs: [
            "frameworks/av/aidl",
            "frameworks/base/media/aidl",
            "frameworks/native/libs/permission/aidl",
        ],
    },
}

droiddoc {
    name: "offline-sdk-docs",
    defaults: ["framework-docs-default"],
    srcs: [
        ":framework-doc-stubs{.exportable}",
    ],
    hdf: [
        "android.whichdoc offline",
    ],
    compat_config: ":global-compat-config",
    proofread_file: "offline-sdk-docs-proofread.txt",
    flags: [
        "-offlinemode",
        "-title \"Android SDK\"",
    ],
    static_doc_index_redirect: "docs/docs-preview-index.html",
}

droiddoc {
    // Please sync with android-api-council@ before making any changes for the name property below.
    // Since there's cron jobs that fetch offline-sdk-referenceonly-docs-docs.zip periodically.
    // See b/116221385 for reference.
    name: "offline-sdk-referenceonly-docs",
    defaults: ["framework-docs-default"],
    srcs: [
        ":framework-doc-stubs{.exportable}",
    ],
    hdf: [
        "android.whichdoc offline",
    ],
    proofread_file: "offline-sdk-referenceonly-docs-proofread.txt",
    flags: [
        "-offlinemode",
        "-title \"Android SDK\"",
        "-referenceonly",
    ],
    static_doc_index_redirect: "docs/docs-documentation-redirect.html",
    static_doc_properties: "docs/source.properties",
}

droiddoc {
    // Please sync with android-api-council@ before making any changes for the name property below.
    // Since there's cron jobs that fetch offline-system-sdk-referenceonly-docs-docs.zip periodically.
    // See b/116221385 for reference.
    name: "offline-system-sdk-referenceonly-docs",
    defaults: ["framework-docs-default"],
    srcs: [
        ":framework-doc-system-stubs",
    ],
    hdf: [
        "android.whichdoc offline",
    ],
    proofread_file: "offline-system-sdk-referenceonly-docs-proofread.txt",
    flags: [
        "-hide 101",
        "-hide 104",
        "-hide 108",
        "-offlinemode",
        "-title \"Android System SDK\"",
        "-referenceonly",
    ],
    static_doc_index_redirect: "docs/docs-documentation-redirect.html",
    static_doc_properties: "docs/source.properties",
}

droiddoc {
    name: "ds-docs-java",
    defaults: ["framework-docs-default"],
    srcs: [
        ":framework-doc-stubs{.exportable}",
    ],
    hdf: [
        "android.whichdoc online",
        "android.hasSamples true",
    ],
    proofread_file: "ds-docs-proofread.txt",
    flags: [
        " -toroot /",
        "-yamlV2",
        "-samplegroup Admin",
        "-samplegroup Background",
        "-samplegroup Connectivity",
        "-samplegroup Content",
        "-samplegroup Input",
        "-samplegroup Media",
        "-samplegroup Notification",
        "-samplegroup RenderScript",
        "-samplegroup Security",
        "-samplegroup Sensors",
        "-samplegroup System",
        "-samplegroup Testing",
        "-samplegroup UI",
        "-samplegroup Views",
        "-samplegroup Wearable",
        "-devsite",
        "-samplesdir",
        "development/samples/browseable",
    ],
}

droiddoc {
    name: "ds-docs-kt",
    srcs: [
        ":framework-doc-stubs{.exportable}",
    ],
    flags: [
        "-noJdkLink",
        "-links https://kotlinlang.org/api/latest/jvm/stdlib/^external/dokka/package-list",
        "-noStdlibLink",
    ],
    proofread_file: "ds-dokka-proofread.txt",
    dokka_enabled: true,
}

java_genrule {
    name: "ds-docs",
    tools: [
        "zip2zip",
        "merge_zips",
    ],
    srcs: [
        ":ds-docs-java{.docs.zip}",
        ":ds-docs-kt{.docs.zip}",
    ],
    out: ["ds-docs.zip"],
    dist: {
        targets: ["docs"],
    },
    cmd: "$(location zip2zip) -i $(location :ds-docs-kt{.docs.zip}) -o $(genDir)/ds-docs-kt-moved.zip **/*:en/reference/kotlin && " +
        "$(location merge_zips) $(out) $(location :ds-docs-java{.docs.zip}) $(genDir)/ds-docs-kt-moved.zip",
}

java_genrule {
    name: "ds-docs-switched",
    tools: [
        "switcher4",
        "soong_zip",
    ],
    srcs: [
        ":ds-docs-java{.docs.zip}",
        ":ds-docs-kt{.docs.zip}",
    ],
    out: ["ds-docs-switched.zip"],
    dist: {
        targets: ["docs"],
    },
    cmd: "unzip -q $(location :ds-docs-java{.docs.zip}) -d $(genDir) && " +
        "unzip -q $(location :ds-docs-kt{.docs.zip}) -d $(genDir)/en/reference/kotlin && " +
        "SWITCHER=$$(cd $$(dirname $(location switcher4)) && pwd)/$$(basename $(location switcher4)) && " +
        "(cd $(genDir)/en/reference && $$SWITCHER --work platform) > /dev/null && " +
        "$(location soong_zip) -o $(out) -C $(genDir) -D $(genDir)",
}

droiddoc {
    name: "ds-static-docs",
    defaults: ["framework-docs-default"],
    srcs: [
        ":framework-doc-stubs{.exportable}",
    ],
    hdf: [
        "android.whichdoc online",
    ],
    flags: [
        "-staticonly",
        "-toroot /",
        "-devsite",
        "-ignoreJdLinks",
    ],
}

droiddoc {
    name: "ds-ref-navtree-docs",
    defaults: ["framework-docs-default"],
    srcs: [
        ":framework-doc-stubs{.exportable}",
    ],
    hdf: [
        "android.whichdoc online",
    ],
    flags: [
        "-toroot /",
        "-atLinksNavtree",
        "-navtreeonly",
    ],
}