Merge topic 'java-documentation-update'

8d23264b50 FindJava: Update module documentation
047bf93748 FindJNI: Update module documentation
b6104f87cc FindJNI: Add Ubuntu 18.04 path to java-11-openjdk

Acked-by: Kitware Robot <kwrobot@kitware.com>
Merge-request: !2436

2 files changed, 59 insertions, 33 deletions

diff --git a/Modules/FindJNI.cmake b/Modules/FindJNI.cmake
index 4913e05..fdddcc7 100644
--- a/Modules/FindJNI.cmake
+++ b/Modules/FindJNI.cmake
@@ -1,29 +1,49 @@
 # Distributed under the OSI-approved BSD 3-Clause License.  See accompanying
 # file Copyright.txt or https://cmake.org/licensing for details.
 
-#.rst:
-# FindJNI
-# -------
-#
-# Find JNI java libraries.
-#
-# This module finds if Java is installed and determines where the
-# include files and libraries are.  It also determines what the name of
-# the library is.  The caller may set variable JAVA_HOME to specify a
-# Java installation prefix explicitly.
-#
-# This module sets the following result variables:
-#
-# ::
-#
-#   JNI_INCLUDE_DIRS      = the include dirs to use
-#   JNI_LIBRARIES         = the libraries to use
-#   JNI_FOUND             = TRUE if JNI headers and libraries were found.
-#   JAVA_AWT_LIBRARY      = the path to the jawt library
-#   JAVA_JVM_LIBRARY      = the path to the jvm library
-#   JAVA_INCLUDE_PATH     = the include path to jni.h
-#   JAVA_INCLUDE_PATH2    = the include path to jni_md.h
-#   JAVA_AWT_INCLUDE_PATH = the include path to jawt.h
+#[=======================================================================[.rst:
+FindJNI
+-------
+
+Find Java Native Interface (JNI) libraries.
+
+JNI enables Java code running in a Java Virtual Machine (JVM) to call
+and be called by native applications and libraries written in other
+languages such as C, C++.
+
+This module finds if Java is installed and determines where the
+include files and libraries are.  It also determines what the name of
+the library is.  The caller may set variable ``JAVA_HOME`` to specify a
+Java installation prefix explicitly.
+
+Result Variables
+^^^^^^^^^^^^^^^^
+
+This module sets the following result variables:
+
+``JNI_INCLUDE_DIRS``
+  the include dirs to use
+``JNI_LIBRARIES``
+  the libraries to use (JAWT and JVM)
+``JNI_FOUND``
+  TRUE if JNI headers and libraries were found.
+
+Cache Variables
+^^^^^^^^^^^^^^^
+
+The following cache variables are also available to set or use:
+
+``JAVA_AWT_LIBRARY``
+  the path to the Java AWT Native Interface (JAWT) library
+``JAVA_JVM_LIBRARY``
+  the path to the Java Virtual Machine (JVM) library
+``JAVA_INCLUDE_PATH``
+  the include path to jni.h
+``JAVA_INCLUDE_PATH2``
+  the include path to jni_md.h and jniport.h
+``JAVA_AWT_INCLUDE_PATH``
+  the include path to jawt.h
+#]=======================================================================]
 
 # Expand {libarch} occurrences to java_libarch subdirectory(-ies) and set ${_var}
 macro(java_append_library_directories _var)
@@ -187,6 +207,7 @@ JAVA_APPEND_LIBRARY_DIRECTORIES(JAVA_AWT_LIBRARY_DIRECTORIES
   /usr/lib/jvm/default/jre/lib/{libarch}
   /usr/lib/jvm/default/lib/{libarch}
   # Ubuntu specific paths for default JVM
+  /usr/lib/jvm/java-11-openjdk-{libarch}/jre/lib/{libarch}    # Ubuntu 18.04 LTS
   /usr/lib/jvm/java-8-openjdk-{libarch}/jre/lib/{libarch}     # Ubuntu 15.10
   /usr/lib/jvm/java-7-openjdk-{libarch}/jre/lib/{libarch}     # Ubuntu 15.10
   /usr/lib/jvm/java-6-openjdk-{libarch}/jre/lib/{libarch}     # Ubuntu 15.10
diff --git a/Modules/FindJava.cmake b/Modules/FindJava.cmake
index cddc5d2..bcdf166 100644
--- a/Modules/FindJava.cmake
+++ b/Modules/FindJava.cmake
@@ -8,19 +8,19 @@
 # Find Java
 #
 # This module finds if Java is installed and determines where the
-# include files and libraries are.  The caller may set variable JAVA_HOME
+# include files and libraries are.  The caller may set variable ``JAVA_HOME``
 # to specify a Java installation prefix explicitly.
 #
-# See also the :module:`FindJNI` module to find Java development tools.
+# See also the :module:`FindJNI` module to find Java Native Interface (JNI).
 #
 # Specify one or more of the following components as you call this find module. See example below.
 #
 # ::
 #
-#   Runtime     = User just want to execute some Java byte-compiled
+#   Runtime     = Java Runtime Environment used to execute Java byte-compiled applications
 #   Development = Development tools (java, javac, javah, jar and javadoc), includes Runtime component
-#   IdlJ        = idl compiler for Java
-#   JarSigner   = signer tool for jar
+#   IdlJ        = Interface Description Language (IDL) to Java compiler
+#   JarSigner   = Signer and verifier tool for Java Archive (JAR) files
 #
 #
 # This module sets the following result variables:
@@ -44,14 +44,18 @@
 #
 #
 # The minimum required version of Java can be specified using the
-# standard CMake syntax, e.g.  find_package(Java 1.5)
+# :command:`find_package` syntax, e.g.
 #
-# NOTE: ${Java_VERSION} and ${Java_VERSION_STRING} are not guaranteed to
+# .. code-block:: cmake
+#
+#   find_package(Java 1.8)
+#
+# NOTE: ``${Java_VERSION}`` and ``${Java_VERSION_STRING}`` are not guaranteed to
 # be identical.  For example some java version may return:
-# Java_VERSION_STRING = 1.5.0_17 and Java_VERSION = 1.5.0.17
+# ``Java_VERSION_STRING = 1.8.0_17`` and ``Java_VERSION = 1.8.0.17``
 #
-# another example is the Java OEM, with: Java_VERSION_STRING = 1.6.0-oem
-# and Java_VERSION = 1.6.0
+# another example is the Java OEM, with: ``Java_VERSION_STRING = 1.8.0-oem``
+# and ``Java_VERSION = 1.8.0``
 #
 # For these components the following variables are set:
 #
@@ -67,6 +71,7 @@
 # ::
 #
 #   find_package(Java)
+#   find_package(Java 1.8 REQUIRED)
 #   find_package(Java COMPONENTS Runtime)
 #   find_package(Java COMPONENTS Development)