Improve jni_generator sample documentation.

Add details of C++ registration, build file modifications.

Review URL: https://codereview.chromium.org/1123343005

Cr-Commit-Position: refs/heads/master@{#330944}

base/android/jni_generator/java/src/org/chromium/example/jni_generator/SampleForTests.java

@@ -101,7 +101,7 @@ class SampleForTests {
     }
 
     public void startExample() {
-        // Calls native code and holds a pointer to the C++ class.
+        // Calls C++ Init(...) method and holds a pointer to the C++ class.
         mNativeCPPObject = nativeInit("myParam");
     }
 

base/android/jni_generator/sample_for_tests.cc

@@ -7,8 +7,10 @@
 #include "base/android/jni_android.h"
 #include "base/android/jni_string.h"
 #include "base/android/scoped_java_ref.h"
-#include "jni/SampleForTests_jni.h"
-
+// Generated file for JNI bindings from C++ to Java @CalledByNative methods.
+// Only to be included in one .cc file.
+// Name is based on the java file name: *.java -> jni/*_jni.h
+#include "jni/SampleForTests_jni.h"  // Generated by JNI.
 
 using base::android::AttachCurrentThread;
 using base::android::ScopedJavaLocalRef;
@@ -26,6 +28,11 @@ CPPClass::CPPClass() {
 CPPClass::~CPPClass() {
 }
 
+// static
+bool CPPClass::RegisterJNI(JNIEnv* env) {
+  return RegisterNativesImpl(env);  // Generated in SampleForTests_jni.h
+}
+
 void CPPClass::Destroy(JNIEnv* env, jobject obj) {
   delete this;
 }

base/android/jni_generator/sample_for_tests.h

@@ -20,13 +20,132 @@ namespace android {
 // - ensure sample_for_tests_jni.h compiles and the functions declared in it
 // as expected.
 //
-// All methods are called directly from Java. See more documentation in
-// SampleForTests.java.
+// Methods are called directly from Java (except RegisterJNI). More
+// documentation in SampleForTests.java
+//
+// For C++ to access Java methods:
+// - GYP Build must be configured to generate bindings:
+//  # ...
+//  'targets': [
+//    {
+//      # An example target that will rely on JNI:
+//      'target_name': 'foo',
+//      'type': '<(component)',
+//      # ... normal sources, defines, deps.
+//      #     For each jni generated .java -> .h header file in foo_jni_headers
+//      #     target there will be a single .cc file here that includes it.
+//      #
+//      # Add deps for JNI:
+//      'conditions': [
+//        ['OS == "android"', {
+//          'dependencies': [
+//            'foo_java',
+//            'foo_jni_headers',
+//          ],
+//        }],
+//      ],
+//    },
+//  ],
+//  # ...
+//  # Create targets for JNI:
+//  'conditions': [
+//    ['OS == "android"', {
+//      'targets': [
+//        {
+//          'target_name': 'foo_jni_headers',
+//          'type': 'none',
+//          'sources': [
+//            'java/src/org/chromium/example/jni_generator/SampleForTests.java',
+//          ],
+//          'variables': {
+//            'jni_gen_package': 'foo',
+//          },
+//          'includes': [ '../../../build/jni_generator.gypi' ],
+//        },
+//        {
+//          'target_name': 'foo_java',
+//          'type': 'none',
+//          'dependencies': [
+//            '../../../base/base.gyp:base',
+//          ],
+//          'variables': {
+//            'java_in_dir': 'java',
+//          },
+//          'includes': [ '../../../build/java.gypi' ],
+//        },
+//      ],
+//    }],
+//  ],
+//
+// - GN Build must be configured to generate bindings:
+//  # Add import at top of file:
+//  if (is_android) {
+//    import("//build/config/android/rules.gni")  # For generate_jni().
+//  }
+//  # ...
+//  # An example target that will rely on JNI:
+//  component("foo") {
+//    # ... normal sources, defines, deps.
+//    #     For each jni generated .java -> .h header file in jni_headers
+//    #     target there will be a single .cc file here that includes it.
+//    #
+//    # Add a dep for JNI:
+//    if (is_android) {
+//      deps += [ ":foo_jni" ]
+//    }
+//  }
+//  # ...
+//  # Create target for JNI:
+//  if (is_android) {
+//    generate_jni("jni_headers") {
+//      sources = [
+//        "java/src/org/chromium/example/jni_generator/SampleForTests.java",
+//      ]
+//      jni_package = "foo"
+//    }
+//    android_library("java") {
+//      java_files = [
+//        "java/src/org/chromium/example/jni_generator/SampleForTests.java",
+//        "java/src/org/chromium/example/jni_generator/NonJniFile.java",
+//      ]
+//    }
+//  }
+//
+// For C++ methods to be exposed to Java:
+// - The generated RegisterNativesImpl method must be called, this is typically
+//   done by having a static RegisterJNI method in the C++ class.
+// - The RegisterJNI method is added to a module's collection of register
+//   methods, such as: example_jni_registrar.h/cc files which call
+//   base::android::RegisterNativeMethods.
+//   An example_jni_registstrar.cc:
+//
+//     namespace {
+//     const base::android::RegistrationMethod kRegisteredMethods[] = {
+//         // Initial string is for debugging only.
+//         { "ExampleName", base::ExampleNameAndroid::RegisterJNI },
+//         { "ExampleName2", base::ExampleName2Android::RegisterJNI },
+//     };
+//     }  // namespace
+//
+//     bool RegisterModuleNameJni(JNIEnv* env) {
+//       return RegisterNativeMethods(env, kRegisteredMethods,
+//                                    arraysize(kRegisteredMethods));
+//     }
+//
+//  - Each module's RegisterModuleNameJni must be called by a larger module,
+//    or application during startup.
+//
 class CPPClass {
  public:
   CPPClass();
   ~CPPClass();
 
+  // Register C++ methods exposed to Java using JNI.
+  static bool RegisterJNI(JNIEnv* env);
+
+  // Java @CalledByNative methods implicitly available to C++ via the _jni.h
+  // file included in the .cc file.
+
   class InnerClass {
    public:
     jdouble MethodOtherP0(JNIEnv* env, jobject obj);