Improve jni_generator sample documentation.

base/android/jni_generator/sample_for_tests.h

 // Copyright (c) 2013 The Chromium Authors. All rights reserved.
 // Use of this source code is governed by a BSD-style license that can be
 // found in the LICENSE file.
 
 #ifndef BASE_ANDROID_JNI_GENERATOR_SAMPLE_FOR_TESTS_H_
 #define BASE_ANDROID_JNI_GENERATOR_SAMPLE_FOR_TESTS_H_
 
 #include <jni.h>
 #include <map>
 #include <string>
 
 #include "base/android/jni_android.h"
 #include "base/basictypes.h"
 
 namespace base {
 namespace android {
 
 // This file is used to:
 // - document the best practices and guidelines on JNI usage.
 // - 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);
   };
 
   void Destroy(JNIEnv* env, jobject obj);
 
   jint Method(JNIEnv* env, jobject obj);
 
   void AddStructB(JNIEnv* env, jobject obj, jobject structb);
 
   void IterateAndDoSomethingWithStructB(JNIEnv* env, jobject obj);
 
   base::android::ScopedJavaLocalRef<jstring> ReturnAString(
       JNIEnv* env, jobject obj);
 
  private:
   std::map<long, std::string> map_;
 
   DISALLOW_COPY_AND_ASSIGN(CPPClass);
 };
 
 }  // namespace android
 }  // namespace base
 
 #endif  // BASE_ANDROID_JNI_GENERATOR_SAMPLE_FOR_TESTS_H_