| Pete Gillin | 0728b74 | 2018-09-17 15:41:45 +0100 | [diff] [blame] | 1 | This directory contains annotated stub files which can be merged into |
| 2 | the main source files by metalava when it is producing API stubs. This |
| 3 | mechanism is used instead of adding the annotations to the main source |
| 4 | files, to avoid carrying patches against the upstream sources. |
| 5 | |
| 6 | Directory structure |
| 7 | =================== |
| 8 | |
| 9 | libcore/ojluni/annotations/sdk: |
| 10 | - Contains annotations to be included in the public SDK, for example |
| 11 | annotations specifying additional details about method contracts. |
| 12 | |
| 13 | libcore/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. |
| Pete Gillin | 941d617 | 2018-09-27 17:57:29 +0100 | [diff] [blame] | 17 | - To add some new files under this directory: |
| 18 | 1. make openjdk-sdk-stubs-no-javadoc |
| Victor Chang | 8055fc2 | 2022-01-18 09:58:26 +0000 | [diff] [blame] | 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 |
| Pete Gillin | 941d617 | 2018-09-27 17:57:29 +0100 | [diff] [blame] | 20 | 3. Add nullability annotations to the new files. |
| 21 | - To see the effect of the files under this directory: |
| 22 | 1. make api-stubs-docs |
| 23 | 2. Look for the file under out/soong/.intermediates/frameworks/base/api-stubs-docs/android_common/stubsDir/ |
| 24 | |
| 25 | libcore/ojluni/annotations/mmodule: |
| 26 | - Contains annotations which determine what is included in the core-platform |
| 27 | and intra-core APIs. See the documentation in libcore/openjdk_java_files.bp. |
| 28 | - To add some new files under this directory: |
| 29 | 1. In libcore/openjdk_java_files.bp, move the files from the |
| 30 | openjdk_internal_files filegroup to openjdk_mmodule_extra_files. *DO NOT* |
| 31 | check in this change, it will have undesirable consequences until you |
| 32 | reach step 4, below. |
| 33 | 2. make openjdk-mmodule-stubs-no-javadoc |
| Victor Chang | 82f70f4 | 2021-05-27 12:30:53 +0100 | [diff] [blame] | 34 | 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 |
| 35 | 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. |
| Victor Chang | bacbadb | 2021-07-23 16:24:08 +0100 | [diff] [blame] | 36 | 5. Add @android.annotation.SystemApi(client = MODULE_LIBRARIES) and @libcore.api.IntraCoreApi as desired |
| Pete Gillin | 941d617 | 2018-09-27 17:57:29 +0100 | [diff] [blame] | 37 | to the classes and members. |
| 38 | - To see the effect of the files under this directory: |
| 39 | 1. make make core-platform-api-stubs core-intra-stubs |
| 40 | 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 |