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 mkdir -p libcore/ojluni/annotations/sdk/nullability/$(dirname ${FILE}) && cp out/soong/.intermediates/libcore/openjdk-sdk-stubs-no-javadoc/android_common/stubsDir/${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. make api-stubs-docs
23   2. Look for the file under out/soong/.intermediates/frameworks/base/api-stubs-docs/android_common/stubsDir/
24
25libcore/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
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}) && cp out/soong/.intermediates/libcore/openjdk-mmodule-stubs-no-javadoc/android_common/stubsDir/${FILE} libcore/ojluni/annotations/mmodule/${FILE/%.java/.annotated.java}; done
35   4. Add @libcore.api.Hide to each top-level class 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.
36   5. Add @libcore.api.CorePlatformApi and @libcore.api.IntraCoreApi as desired
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
41