Add more comments to java_fuzz_test examples

examples/java/BUILD

@@ -52,18 +52,26 @@ java_fuzz_test(
     tags = [
         "no-oss-fuzz",
     ],
+    # The JVM expects a native library on macOS to have the .dylib extension,
+    # but due to a bug in Bazel the shared library extension defaults to .so
+    # there. This can be worked around by specifying the desired extension in
+    # the name of the rule and selecting the correct one based on the platform.
+    # See https://github.com/bazelbuild/bazel/issues/11082.
     deps = select({
         "@platforms//os:macos": [":libnative.dylib"],
         "//conditions:default": [":native"],
     }),
 )
 
+# A Java fuzz test with a native library, both of which have declared data
+# dependencies that they can access at runtime.
 java_fuzz_test(
     name = "NativeRunfileFuzzTest",
     srcs = ["com/example/NativeRunfileFuzzTest.java"],
     data = [
         "corpus_0.txt",
     ],
+    # See NativeFuzzTest for why this uses a select.
     deps = select({
         "@platforms//os:macos": [":libnative_runfile.dylib"],
         "//conditions:default": [":native_runfile"],
@@ -72,25 +80,32 @@ java_fuzz_test(
     ],
 )
 
+# A Java fuzz test with a native library that calls a function through a pointer
+# of an incorrect type, which is detected by UBSan.
 java_fuzz_test(
     name = "NativeUbsanFuncPtrFuzzTest",
     srcs = ["com/example/NativeUbsanFuncPtrFuzzTest.java"],
-    deps = [
-        ":native_ubsan_func_ptr",
-    ],
+    deps = select({
+        "@platforms//os:macos": [":libnative_ubsan_func_ptr.dylib"],
+        "//conditions:default": [":native_ubsan_func_ptr"],
+    }),
 )
 
 # A native library that interfaces with Java through the JNI.
+# It contains an out-of-bounds read is detected by ASan.
 cc_binary(
     name = "native",
+    # Build as a shared library that can be loaded by a Java application at
+    # runtime via System.loadLibrary().
     linkshared = True,
     tags = ["manual"],
     deps = [
         ":native_lib",
     ],
 )
 
-# Workaround for https://github.com/bazelbuild/bazel/issues/11082.
+# The same shared library as :native, but with the correct extension for macOS.
+# See the comment on :NativeFuzzTest for why this is needed.
 cc_binary(
     name = "libnative.dylib",
     linkshared = True,
@@ -100,6 +115,8 @@ cc_binary(
     ],
 )
 
+# The implementation shared by :native and :libnative.dylib, which differ only
+# in the name of the resulting shared library.
 cc_library(
     name = "native_lib",
     srcs = [
@@ -109,24 +126,27 @@ cc_library(
     deps = [
         "@bazel_tools//tools/jdk:jni",
     ],
+    # Required because :native and :libnative.dylib to not reference any symbols
+    # of this library, which means that it wouldn't be linked at all without
+    # this.
     alwayslink = True,
 )
 
+# A shared library that demonstrates that fuzz targets can find their Bazel
+# data dependencies at runtime, both from Java and native code.
 cc_binary(
     name = "native_runfile",
-    # Build as a shared library that can be loaded by a Java application at
-    # runtime via System.loadLibrary().
     linkshared = True,
     tags = ["manual"],
     deps = [
         ":native_runfile_lib",
     ],
 )
 
+# The same shared library as :native_runfile, but with the correct extension for
+# macOS. See the comment on :NativeFuzzTest for why this is needed.
 cc_binary(
     name = "libnative_runfile.dylib",
-    # Build as a shared library that can be loaded by a Java application at
-    # runtime via System.loadLibrary().
     linkshared = True,
     tags = ["manual"],
     deps = [
@@ -152,12 +172,30 @@ cc_library(
 
 cc_binary(
     name = "native_ubsan_func_ptr",
+    linkshared = True,
+    tags = ["manual"],
+    deps = [
+        ":native_ubsan_func_ptr_lib",
+    ],
+)
+
+cc_binary(
+    name = "libnative_ubsan_func_ptr.dylib",
+    linkshared = True,
+    tags = ["manual"],
+    deps = [
+        ":native_ubsan_func_ptr_lib",
+    ],
+)
+
+cc_library(
+    name = "native_ubsan_func_ptr_lib",
     srcs = [
         "com/example/NativeUbsanFuncPtrFuzzTest.cpp",
         "com/example/NativeUbsanFuncPtrFuzzTest.h",
     ],
-    linkshared = True,
     deps = [
         "@bazel_tools//tools/jdk:jni",
     ],
+    alwayslink = True,
 )