Donate to e Foundation | Murena handsets with /e/OS | Own a part of Murena! Learn more

Commit 0a2e8716 authored by Paul Duffin's avatar Paul Duffin
Browse files

aapt2: Use android.annotation.Hide instead of @hide 

Previously, `aapt2` would simply pass an `@hide` doctag through to the
generated `Manifest.java` or `R.java` files and would rely on Metalava
to do the right thing with it. While Metalava does currently support
that it now considers an `@hide` doc tag that is not a block tag, i.e.
start on its own line, as invalid and will report it as an error.

Rather than add custom code to move the `@hide` doctag to the correct
location, or require changes to the resource files where the `@hide`
doctags are written this change leverages the existing support for
handling annotations like `@SystemApi` to replace the `@hide` doctag
with an `@android.annotation.Hide` annotation.

Tests were added to `AnnotationProcessor_test.cpp` to test the handling
of `@hide` and other tests that were broken by this change were fixed.
One test was actually invalid as it specified `@TestApi` without
`@hide` so that too was fixed.

This change did cause a slight change to the contents of the
`framework-doc-system-stubs` as previously the Javadoc comments
still included `@hide` doctags but this change removes them.

Flag: EXEMPT build refactoring
Bug: 444151586
Test: m checkapi
Change-Id: I01c476ef2f47261001d8c89d0218897e45336b40
parent 555d47a6

tools/aapt2/java/AnnotationProcessor.cpp

+3 −1
Original line number Diff line number Diff line
@@ -50,6 +50,7 @@ struct AnnotationRule { 
    kSystemApi = 0x02,

    kTestApi = 0x04,

    kFlaggedApi = 0x08,

    kHide = 0x10,

  };



  StringPiece doc_str;
@@ -58,10 +59,11 @@ struct AnnotationRule { 
  bool preserve_params;

};



static std::array<AnnotationRule, 3> sAnnotationRules = {{

static std::array<AnnotationRule, 4> sAnnotationRules = {{

    {"@SystemApi", AnnotationRule::kSystemApi, "@android.annotation.SystemApi", true},

    {"@TestApi", AnnotationRule::kTestApi, "@android.annotation.TestApi", false},

    {"@FlaggedApi", AnnotationRule::kFlaggedApi, "@android.annotation.FlaggedApi", true},

    {"@hide", AnnotationRule::kHide, "@android.annotation.Hide", false},

}};



void AnnotationProcessor::AppendCommentLine(std::string comment, bool add_api_annotations) {

tools/aapt2/java/AnnotationProcessor_test.cpp

+32 −0
Original line number Diff line number Diff line
@@ -121,6 +121,38 @@ TEST(AnnotationProcessorTest, EmitsTestApiAnnotationAndRemovesFromComment) { 
  EXPECT_THAT(annotations, HasSubstr("This is a test API"));

}



TEST(AnnotationProcessorTest, EmitsHideAnnotationAndRemovesFromComment) {

  AnnotationProcessor processor;

  processor.AppendComment("@hide This is an internal API");



  std::string annotations;

  StringOutputStream out(&annotations);

  Printer printer(&out);

  processor.Print(&printer);

  out.Flush();



  EXPECT_THAT(annotations, HasSubstr("@android.annotation.Hide"));

  EXPECT_THAT(annotations, Not(HasSubstr("@hide")));

  EXPECT_THAT(annotations, HasSubstr("This is an internal API"));

}



TEST(AnnotationProcessorTest, EmitsSystemApiAndHideAnnotationAndRemovesFromComment) {

  AnnotationProcessor processor;

  processor.AppendComment("@SystemApi @hide This is a system API");



  std::string annotations;

  StringOutputStream out(&annotations);

  Printer printer(&out);

  processor.Print(&printer);

  out.Flush();



  EXPECT_THAT(annotations, HasSubstr("@android.annotation.SystemApi"));

  EXPECT_THAT(annotations, Not(HasSubstr("@SystemApi")));

  EXPECT_THAT(annotations, HasSubstr("@android.annotation.Hide"));

  EXPECT_THAT(annotations, Not(HasSubstr("@hide")));

  EXPECT_THAT(annotations, HasSubstr("This is a system API"));

}



TEST(AnnotationProcessorTest, NotEmitSystemApiAnnotation) {

  AnnotationProcessor processor;

  processor.AppendComment("@SystemApi This is a system API");

tools/aapt2/java/JavaClassGenerator_test.cpp

+1 −1
Original line number Diff line number Diff line
@@ -449,7 +449,7 @@ TEST(JavaClassGeneratorTest, CommentsForStyleableHiddenAttributesAreNotPresent) 
  EXPECT_THAT(output, Not(HasSubstr("@see #Container_one")));

  EXPECT_THAT(output, HasSubstr("attr name android:one"));

  EXPECT_THAT(output, HasSubstr("attr description"));

  EXPECT_THAT(output, HasSubstr(attr.GetComment()));

  EXPECT_THAT(output, HasSubstr("This is an attribute"));

  EXPECT_THAT(output, HasSubstr(styleable.GetComment()));

}

tools/aapt2/java/ManifestClassGenerator_test.cpp

+3 −3
Original line number Diff line number Diff line
@@ -88,7 +88,7 @@ TEST(ManifestClassGeneratorTest, CommentsAndAnnotationsArePresent) { 
             @hide

             @SystemApi -->

        <permission android:name="android.permission.SECRET" />

        <!-- @TestApi This is a test only permission. -->

        <!-- @hide @TestApi This is a test only permission. -->

        <permission android:name="android.permission.TEST_ONLY" />

      </manifest>)");
@@ -112,9 +112,9 @@ TEST(ManifestClassGeneratorTest, CommentsAndAnnotationsArePresent) { 


  const char* expected_secret = R"(    /**

     * This is a private permission for system only!

     * @hide

     */

    @android.annotation.SystemApi

    @android.annotation.Hide

    public static final String SECRET="android.permission.SECRET";)";

  EXPECT_THAT(actual, HasSubstr(expected_secret));
@@ -122,6 +122,7 @@ TEST(ManifestClassGeneratorTest, CommentsAndAnnotationsArePresent) { 
     * This is a test only permission.

     */

    @android.annotation.TestApi

    @android.annotation.Hide

    public static final String TEST_ONLY="android.permission.TEST_ONLY";)";

  EXPECT_THAT(actual, HasSubstr(expected_test));

}
@@ -163,7 +164,6 @@ TEST(ManifestClassGeneratorTest, CommentsAndAnnotationsArePresentButNoApiAnnotat 


  const char* expected_secret = R"(    /**

     * This is a private permission for system only!

     * @hide

     */

    public static final String SECRET="android.permission.SECRET";)";

  EXPECT_THAT(actual, HasSubstr(expected_secret));