Improve jni_generator sample documentation.

base/android/jni_generator/sample_for_tests.h

Index: base/android/jni_generator/sample_for_tests.h
diff --git a/base/android/jni_generator/sample_for_tests.h b/base/android/jni_generator/sample_for_tests.h
index c98cf97693638963a322c3fd582bb7f541f526b1..17f62ad69f6b2411376832a814e5add0067d0d18 100644
--- a/base/android/jni_generator/sample_for_tests.h
+++ b/base/android/jni_generator/sample_for_tests.h
@@ -20,13 +20,98 @@ 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:
+// - Build must be configured to generate bindings:
+//
+//  GYP:
+//  # ...
+//  'conditions': [
+//    ['OS == "android"', {
+//      'targets': [
+//        {
+//          'target_name': 'base_jni_generator_sample_jni_headers',
+//          'type': 'none',
+//          'sources': [
+//            'java/src/org/chromium/example/jni_generator/SampleForTests.java',
+//          ],
+//          'variables': {
+//            'jni_gen_package': 'base_jni_generator_sample',
+//          },
+//          'includes': [ '../../../build/jni_generator.gypi' ],
+//        },
+//        {
+//          'target_name': 'base_jni_generator_sample_java',
+//          'type': 'none',
+//          'dependencies': [
+//            '../../../base/base.gyp:base',
+//          ],
+//          'variables': {
+//            'java_in_dir': 'java',
+//          },
+//          'includes': [ '../../../build/java.gypi' ],
+//        },
+//      ],
+//    }],
+//  ],
+//
+//  And these two targets must be dependencies of modules using them.

[nyquist, 2015/05/13 06:47:20]

This is a little bit unclear to me (as a fake new reader).
Could you clarify that the C++ target that has the .cc-file which includes the
_jni.h file is the one that should depend on the _jni_headers target?
And likewise just clarify that the _java target can be depended on by other Java
targets like normal?

[scheib, 2015/05/13 21:59:52]

Done, I've included the deps added in the build file examples. I believe in GYP
both targets should just be included by the C++ target, as they are both
necessary for that target to function.

I've a clean up patch to do this for bluetooth as well
https://codereview.chromium.org/1127043006/

+//
+//  GN:
+//  if (is_android) {
+//    import("//build/config/android/rules.gni")  # For generate_jni().
+//  }
+//  # ...
+//  component("base_jni_generator_sample") {
+//    # ... sources, defines, deps ...
+//    if (is_android) {
+//      deps += [ ":base_jni_generator_sample_jni" ]
+//    }
+//  }
+//
+//  if (is_android) {
+//    generate_jni("base_jni_generator_sample_jni") {
+//      sources = [
+//        "java/src/org/chromium/example/jni_generator/SampleForTests.java",
+//      ]
+//      jni_package = "base_jni_generator_sample"
+//    }
+//  }
+//
+// 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 is then called by a larger module,
+//    or application during startup.
+//
 class CPPClass {
  public:
   CPPClass();
   ~CPPClass();
 
+  // Register C++ methods exposed to Java using JNI.

[nyquist, 2015/05/13 06:47:20]

What about Java methods that are marked with @CalledByNative? (i.e., the other
direction)

[scheib, 2015/05/13 21:59:52]

That doesn't require external C++ setup, it works given the generated headers.
So, just include the header in the .cc and call the functions.

I've added a comment to explain.

+  static bool RegisterJNI(JNIEnv* env);
+
   class InnerClass {
    public:
     jdouble MethodOtherP0(JNIEnv* env, jobject obj);