Deprecate java.generate_native_header() in favor of java.generate_native_headers()

After implementing a much more extensive Java native module than what
currently exists in the tests, I found shortcomings.

1. You need to be able to pass multiple Java files.
2. Meson needs more information to better track the generated native
   headers.
3. Meson wasn't tracking the header files generated from inner classes.

This new function should fix all the issues the old function had with
room to grow should more functionality need to be added. What I
implemented here in this new function is essentially what I have done in
the Heterogeneous-Memory Storage Engine's Java bindings.

2 files changed, 80 insertions, 1 deletions

diff --git a/docs/markdown/Java-module.md b/docs/markdown/Java-module.md
index 9857de7..1665b7b 100644
--- a/docs/markdown/Java-module.md
+++ b/docs/markdown/Java-module.md
@@ -1,11 +1,13 @@
 # Java Module
 
-*Added 0.60.0*
+*(added in 0.60.0)*
 
 ## Functions
 
 ### `generate_native_header()`
 
+*(deprecated in 0.62.0, use `generate_native_headers()`)*
+
 This function will generate a header file for use in Java native module
 development by reading the supplied Java file for `native` method declarations.
 
@@ -13,3 +15,46 @@ Keyword arguments:
 
 - `package`: The [package](https://en.wikipedia.org/wiki/Java_package) of the
 file. If left empty, Meson will assume that there is no package.
+
+### `generate_native_headers()`
+
+*(added in 0.62.0)*
+
+This function will generate native header files for use in Java native module
+development by reading the supplied Java files for `native` method declarations.
+
+Keyword arguments:
+
+- `classes`: The list of class names relative to the `package`, if it exists,
+which contain `native` method declarations. Use `.` separated class names.
+
+- `package`: The [package](https://en.wikipedia.org/wiki/Java_package) of the
+file. If left empty, Meson will assume that there is no package.
+
+Example:
+
+```java
+// Outer.java
+
+package com.mesonbuild;
+
+public class Outer {
+    private static native void outer();
+
+    public static class Inner {
+        private static native void inner();
+    }
+}
+```
+
+With the above file, an invocation would look like the following:
+
+```meson
+java = import('java')
+
+native_headers = java.generate_native_headers(
+    'Outer.java',
+    package: 'com.mesonbuild',
+    classes: ['Outer', 'Outer.Inner']
+)
+```
diff --git a/docs/markdown/snippets/java_generate_native_headers.md b/docs/markdown/snippets/java_generate_native_headers.md
new file mode 100644
index 0000000..2a2a89e
--- /dev/null
+++ b/docs/markdown/snippets/java_generate_native_headers.md
@@ -0,0 +1,34 @@
+## Deprecated `java.generate_native_header()` in favor of the new `java.generate_native_headers()`
+
+`java.generate_native_header()` was only useful for the most basic of
+situations. It didn't take into account that in order to generate native
+headers, you had to have all the referenced Java files. It also didn't take
+into account inner classes. Do not use this function from `0.62.0` onward.
+
+`java.generate_native_headers()` has been added as a replacement which should account for the previous function's shortcomings.
+
+```java
+// Outer.java
+
+package com.mesonbuild;
+
+public class Outer {
+    private static native void outer();
+
+    public static class Inner {
+        private static native void inner();
+    }
+}
+```
+
+With the above file, an invocation would look like the following:
+
+```meson
+java = import('java')
+
+native_headers = java.generate_native_headers(
+    'Outer.java',
+    package: 'com.mesonbuild',
+    classes: ['Outer', 'Outer.Inner']
+)
+```