0
Files
src/docs/android_accessing_cpp_enums_in_java.md
Nate Fischer 93c5915741 Docs: consistent fenced code blocks
No change to logic, only docs. This is a mechanical docs change which
should not impact content (but will improve readability).

This edits some Android docs to use fenced code blocks more
consistently:

 * Prefer fenced code blocks over indented code blocks
 * Fix indentation issues (see coverage.md)
 * Specify a language for syntax highlighting where it makes sense
   (particularly, use the "gn" language where it was omitted)

R=agrieve@chromium.org

Bug: 918221
Test: Upload to gerrit > open file > click "gitiles"
Change-Id: I2a4aa292d3bd1cf67bd0a7bcfb0cb01f7b8ede98
Reviewed-on: https://chromium-review.googlesource.com/c/1451357
Reviewed-by: Andrew Grieve <agrieve@chromium.org>
Commit-Queue: Nate Fischer <ntfschr@chromium.org>
Cr-Commit-Position: refs/heads/master@{#628981}
2019-02-05 01:25:08 +00:00

3.9 KiB

Accessing C++ Enums In Java

[TOC]

Introduction

Accessing C++ enums in Java is implemented via a Python script which analyzes the C++ enum and spits out the corresponding Java class. The enum needs to be annotated in a particular way. By default, the generated class name will be the same as the name of the enum. If all the names of the enum values are prefixed with the MACRO_CASED_ name of the enum those prefixes will be stripped from the Java version.

Features

  • Customize the package name of the generated class using the GENERATED_JAVA_ENUM_PACKAGE directive (required)
  • Customize the class name using the GENERATED_JAVA_CLASS_NAME_OVERRIDE directive (optional)
  • Strip enum entry prefixes to make the generated classes less verbose using the GENERATED_JAVA_PREFIX_TO_STRIP directive (optional)
  • Supports @IntDef
  • Copies comments that directly precede enum entries into the generated Java class

Usage

  1. Add directives to your C++ enum

    // GENERATED_JAVA_ENUM_PACKAGE: org.chromium.chrome
    // GENERATED_JAVA_CLASS_NAME_OVERRIDE: FooBar
    // GENERATED_JAVA_PREFIX_TO_STRIP: BAR_
    enum SomeEnum {
      BAR_A,
      BAR_B,
      BAR_C = BAR_B,
    };
    
  2. Add a new build target

    import("//build/config/android/rules.gni")
    
    java_cpp_enum("foo_generated_enum") {
      sources = [
        "base/android/native_foo_header.h",
      ]
    }
    
  3. Add the new target to the desired android_library targets srcjar_deps:

    android_library("base_java") {
      srcjar_deps = [
        ":foo_generated_enum",
      ]
    }
    
  4. The generated file org/chromium/chrome/FooBar.java would contain:

    package org.chromium.chrome;
    
    import android.support.annotation.IntDef;
    
    import java.lang.annotation.Retention;
    import java.lang.annotation.RetentionPolicy;
    
    @IntDef({
        FooBar.A, FooBar.B, FooBar.C
    })
    @Retention(RetentionPolicy.SOURCE)
    public @interface FooBar {
      int A = 0;
      int B = 1;
      int C = 1;
    }
    

Formatting Notes

  • Handling long package names:

    // GENERATED_JAVA_ENUM_PACKAGE: (
    //   org.chromium.chrome.this.package.is.too.long.to.fit.on.a.single.line)
    
  • Enum entries

    • Single line enums should look like this:

      // GENERATED_JAVA_ENUM_PACKAGE: org.foo
      enum NotificationActionType { BUTTON, TEXT };
      
    • Multi-line enums should have one enum entry per line, like this:

      // GENERATED_JAVA_ENUM_PACKAGE: org.foo
      enum NotificationActionType {
        BUTTON,
        TEXT
      };
      
    • Multi-line enum entries are allowed but should be formatted like this:

      // GENERATED_JAVA_ENUM_PACKAGE: org.foo
      enum NotificationActionType {
        LongKeyNumberOne,
        LongKeyNumberTwo,
        ...
        LongKeyNumberThree =
            LongKeyNumberOne | LongKeyNumberTwo | ...
      };
      
  • Preserving comments

    // GENERATED_JAVA_ENUM_PACKAGE: org.chromium
    enum CommentEnum {
      // This comment will be preserved.
      ONE,
      TWO, // This comment will NOT be preserved.
      THREE
    }
    
    ...
    public @interface CommentEnum {
      ...
      /**
       * This comment will be preserved.
       */
      int ONE = 0;
      int TWO = 1;
      int THREE = 2;
    }
    

Code