1This directory contains annotated stub files which can be merged into 2the main source files by metalava when it is producing API stubs. This 3mechanism is used instead of adding the annotations to the main source 4files, to avoid carrying patches against the upstream sources. 5 6Directory structure 7=================== 8 9libcore/ojluni/annotations/sdk: 10 - Contains annotations to be included in the public SDK, for example 11 annotations specifying additional details about method contracts. 12 13libcore/ojluni/annotations/sdk/nullability: 14 - Contains annotations to be included in the public SDK specifically 15 relating to nullability. Adding an annotated stub file to this subdirectory 16 will cause the annotations to be validated for correctness and completeness. 17 - To add some new files under this directory: 18 1. make openjdk-sdk-stubs-no-javadoc 19 2. for FILE in your/package/and/Class.java another/package/AnotherClass.java; do unzip out/soong/.intermediates/libcore/openjdk-sdk-stubs-no-javadoc/android_common/metalava/openjdk-sdk-stubs-no-javadoc-stubs.srcjar ${FILE} -d libcore/ojluni/annotations/sdk/nullability/ && mv libcore/ojluni/annotations/sdk/nullability/$FILE libcore/ojluni/annotations/sdk/nullability/${FILE/%.java/.annotated.java}; done 20 3. Add nullability annotations to the new files. 21 - To see the effect of the files under this directory: 22 1. m art.module.public.api.stubs.source-update-current-api 23 2. Look for the file under libcore/api/ 24 25libcore/ojluni/annotations/flagged_api: 26 - Contains @FlaggedApi annotations to be included in the core_current stubs. 27 - To add some new files under this directory: 28 1. libcore/tools/ojluni-annotations/generate_flagged_api_files.sh your.package.Bar another.package.Foo 29 2. Add @FlaggedApi annotations to the new files. 30 - To see the effect of the files under this directory: 31 1. m art.module.public.api.stubs.source-update-current-api 32 2. Look for the file under libcore/api/ 33 34libcore/ojluni/annotations/mmodule: 35 - Contains annotations which determine what is included in the core-platform 36 and intra-core APIs. See the documentation in libcore/openjdk_java_files.bp. 37 - To add some new files under this directory: 38 1. In libcore/openjdk_java_files.bp, move the files from the 39 openjdk_internal_files filegroup to openjdk_mmodule_extra_files. *DO NOT* 40 check in this change, it will have undesirable consequences until you 41 reach step 4, below. 42 2. make openjdk-mmodule-stubs-no-javadoc 43 3. FILES="your/package/and/Class.java another/package/AnotherClass.java"; for FILE in $FILES; do mkdir -p libcore/ojluni/annotations/mmodule/$(dirname ${FILE}) && unzip out/soong/.intermediates/libcore/openjdk-mmodule-stubs-no-javadoc/android_common/metalava/openjdk-mmodule-stubs-no-javadoc-stubs.srcjar ${FILE} && mv ${FILE} libcore/ojluni/annotations/mmodule/${FILE/%.java/.annotated.java}; done 44 4. Add @libcore.api.Hide to each class, methods and fields in the new files. This will prevent it from being added to the public API. A JavaDoc @hide tag will not work as metalava will ignore javadoc from the stub files. 45 5. Add @android.annotation.SystemApi(client = MODULE_LIBRARIES) and @libcore.api.IntraCoreApi as desired 46 to the classes and members. 47 - To see the effect of the files under this directory: 48 1. make make core-platform-api-stubs core-intra-stubs 49 2. Look for the files under out/soong/.intermediates/libcore/mmodules/core_platform_api/core-platform-api-stubs/android_common/stubsDir/ and out/soong/.intermediates/libcore/mmodules/intracoreapi/core-intra-stubs/android_common/stubsDir 50