UseJava: Refactor documentation for better formatting

Co-Authored-By: Craig Scott <craig.scott@crascit.com>

1 files changed, 229 insertions, 294 deletions

diff --git a/Modules/UseJava.cmake b/Modules/UseJava.cmake
index 5600b4c..b0315b2 100644
--- a/Modules/UseJava.cmake
+++ b/Modules/UseJava.cmake
@@ -8,289 +8,234 @@ UseJava
 Use Module for Java
 
 This file provides functions for Java.  It is assumed that
-FindJava.cmake has already been loaded.  See FindJava.cmake for
+:module:`FindJava` has already been loaded.  See :module:`FindJava` for
 information on how to load Java into your CMake project.
 
-::
+Creating And Installing JARs
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. code-block:: cmake
+
+  add_jar(<target_name>
+          [SOURCES] <source1> [<source2>...] [<resource1>...]
+          [INCLUDE_JARS <jar1> [<jar2>...]]
+          [ENTRY_POINT <entry>]
+          [VERSION <version>]
+          [OUTPUT_NAME <name>]
+          [OUTPUT_DIR <dir>]
+          [GENERATE_NATIVE_HEADERS <target> [DESTINATION <dir>]]
+          )
 
- add_jar(target_name
-         [SOURCES] source1 [source2 ...] [resource1 ...]
-         [INCLUDE_JARS jar1 [jar2 ...]]
-         [ENTRY_POINT entry]
-         [VERSION version]
-         [OUTPUT_NAME name]
-         [OUTPUT_DIR dir]
-         [GENERATE_NATIVE_HEADERS target [DESTINATION dir]]
-         )
-
-This command creates a <target_name>.jar.  It compiles the given
-source files (source) and adds the given resource files (resource) to
+This command creates a ``<target_name>.jar``.  It compiles the given
+``<source>`` files and adds the given ``<resource>`` files to
 the jar file.  Source files can be java files or listing files
-(prefixed by '@').  If only resource files are given then just a jar file
-is created.  The list of include jars are added to the classpath when
+(prefixed by ``@``).  If only resource files are given then just a jar file
+is created.  The list of ``INCLUDE_JARS`` are added to the classpath when
 compiling the java sources and also to the dependencies of the target.
-INCLUDE_JARS also accepts other target names created by add_jar.  For
-backwards compatibility, jar files listed as sources are ignored (as
+``INCLUDE_JARS`` also accepts other target names created by ``add_jar()``.
+For backwards compatibility, jar files listed as sources are ignored (as
 they have been since the first version of this module).
 
-The default OUTPUT_DIR can also be changed by setting the variable
-CMAKE_JAVA_TARGET_OUTPUT_DIR.
+The default ``OUTPUT_DIR`` can also be changed by setting the variable
+``CMAKE_JAVA_TARGET_OUTPUT_DIR``.
 
-Optionally, using option GENERATE_NATIVE_HEADERS, native header files can be generated
-for methods declared as native. These files provide the connective glue that allow your
-Java and C code to interact. An INTERFACE target will be created for an easy usage
-of generated files. Sub-option DESTINATION can be used to specify output directory for
-generated header files.
+Optionally, using option ``GENERATE_NATIVE_HEADERS``, native header files can
+be generated for methods declared as native.  These files provide the
+connective glue that allow your Java and C code to interact.  An INTERFACE
+target will be created for an easy usage of generated files.  Sub-option
+``DESTINATION`` can be used to specify the output directory for generated
+header files.
 
-GENERATE_NATIVE_HEADERS option requires, at least, version 1.8 of the JDK.
+``GENERATE_NATIVE_HEADERS`` option requires, at least, version 1.8 of the JDK.
 
-Additional instructions:
+The ``add_jar()`` function sets the following target properties on
+``<target_name>``:
 
-::
-
-   To add compile flags to the target you can set these flags with
-   the following variable:
+``INSTALL_FILES``
+  The files which should be installed.  This is used by ``install_jar()``.
+``JNI_SYMLINK``
+  The JNI symlink which should be installed.  This is used by
+  ``install_jni_symlink()``.
+``JAR_FILE``
+  The location of the jar file so that you can include it.
+``CLASSDIR``
+  The directory where the class files can be found.  For example to use them
+  with ``javah``.
 
+.. code-block:: cmake
 
+ install_jar(<target_name> <destination>)
+ install_jar(<target_name> DESTINATION <destination> [COMPONENT <component>])
 
-::
-
-       set(CMAKE_JAVA_COMPILE_FLAGS -nowarn)
+This command installs the ``<target_name>`` files to the given
+``<destination>``.  It should be called in the same scope as ``add_jar()`` or
+it will fail.
 
+The ``install_jar()`` function sets the ``INSTALL_DESTINATION`` target
+property on jars so installed.  This property holds the ``<destination>`` as
+described above, and is used by ``install_jar_exports()``.  You can get this
+information with :command:`get_property` and the ``INSTALL_DESTINATION``
+property key.
 
+.. code-block:: cmake
 
-::
-
-   To add a path or a jar file to the class path you can do this
-   with the CMAKE_JAVA_INCLUDE_PATH variable.
-
-
-
-::
-
-       set(CMAKE_JAVA_INCLUDE_PATH /usr/share/java/shibboleet.jar)
-
-
-
-::
-
-   To use a different output name for the target you can set it with:
-
-
-
-::
-
-       add_jar(foobar foobar.java OUTPUT_NAME shibboleet.jar)
-
-
-
-::
+ install_jni_symlink(<target_name> <destination>)
+ install_jni_symlink(<target_name> DESTINATION <destination> [COMPONENT <component>])
 
-   To use a different output directory than CMAKE_CURRENT_BINARY_DIR
-   you can set it with:
+This command installs the ``<target_name>`` JNI symlinks to the given
+``<destination>``.  It should be called in the same scope as ``add_jar()`` or
+it will fail.
 
+.. code-block:: cmake
 
+ install_jar_exports(TARGETS <jars>...
+                     [NAMESPACE <namespace>]
+                     FILE <filename>
+                     DESTINATION <destination> [COMPONENT <component>])
 
-::
-
-       add_jar(foobar foobar.java OUTPUT_DIR ${PROJECT_BINARY_DIR}/bin)
-
-
-
-::
-
-   To define an entry point in your jar you can set it with the ENTRY_POINT
-   named argument:
-
-
-
-::
-
-       add_jar(example ENTRY_POINT com/examples/MyProject/Main)
-
-
-
-::
-
-   To define a custom manifest for the jar, you can set it with the manifest
-   named argument:
-
-
-
-::
-
-       add_jar(example MANIFEST /path/to/manifest)
-
-
-
-::
-
-   To add a VERSION to the target output name you can set it using
-   the VERSION named argument to add_jar. This will create a jar file with the
-   name shibboleet-1.0.0.jar and will create a symlink shibboleet.jar
-   pointing to the jar with the version information.
+This command installs a target export file ``<filename>`` for the named jar
+targets to the given ``<destination>`` directory.  Its function is similar to
+that of :command:`install(EXPORTS)`.
 
+.. code-block:: cmake
 
+ export_jars(TARGETS <jars>...
+             [NAMESPACE <namespace>]
+             FILE <filename>)
 
-::
+This command writes a target export file ``<filename>`` for the named ``<jars>``
+targets.  Its function is similar to that of :command:`export`.
 
-       add_jar(shibboleet shibbotleet.java VERSION 1.2.0)
 
+Examples
+""""""""
 
+To add compile flags to the target you can set these flags with the following
+variable:
 
-::
+.. code-block:: cmake
 
-    If the target is a JNI library, utilize the following commands to
-    create a JNI symbolic link:
+  set(CMAKE_JAVA_COMPILE_FLAGS -nowarn)
 
 
+To add a path or a jar file to the class path you can do this with the
+``CMAKE_JAVA_INCLUDE_PATH`` variable.
 
-::
+.. code-block:: cmake
 
-       set(CMAKE_JNI_TARGET TRUE)
-       add_jar(shibboleet shibbotleet.java VERSION 1.2.0)
-       install_jar(shibboleet ${LIB_INSTALL_DIR}/shibboleet)
-       install_jni_symlink(shibboleet ${JAVA_LIB_INSTALL_DIR})
+  set(CMAKE_JAVA_INCLUDE_PATH /usr/share/java/shibboleet.jar)
 
+To use a different output name for the target you can set it with:
 
+.. code-block:: cmake
 
-::
+  add_jar(foobar foobar.java OUTPUT_NAME shibboleet.jar)
 
-    If a single target needs to produce more than one jar from its
-    java source code, to prevent the accumulation of duplicate class
-    files in subsequent jars, set/reset CMAKE_JAR_CLASSES_PREFIX prior
-    to calling the add_jar() function:
+To use a different output directory than ``CMAKE_CURRENT_BINARY_DIR`` you can
+set it with:
 
+.. code-block:: cmake
 
+  add_jar(foobar foobar.java OUTPUT_DIR ${PROJECT_BINARY_DIR}/bin)
 
-::
+To define an entry point in your jar you can set it with the ``ENTRY_POINT``
+named argument:
 
-       set(CMAKE_JAR_CLASSES_PREFIX com/redhat/foo)
-       add_jar(foo foo.java)
+.. code-block:: cmake
 
+  add_jar(example ENTRY_POINT com/examples/MyProject/Main)
 
+To define a custom manifest for the jar, you can set it with the ``MANIFEST``
+named argument:
 
-::
+.. code-block:: cmake
 
-       set(CMAKE_JAR_CLASSES_PREFIX com/redhat/bar)
-       add_jar(bar bar.java)
+  add_jar(example MANIFEST /path/to/manifest)
 
+To add a version to the target output name you can set it using the ``VERSION``
+named argument to ``add_jar()``.  The following example will create a jar file
+with the name ``shibboleet-1.0.0.jar`` and will create a symlink
+``shibboleet.jar`` pointing to the jar with the version information.
 
+.. code-block:: cmake
 
-::
+  add_jar(shibboleet shibbotleet.java VERSION 1.2.0)
 
-    For an optimum usage of option GENERATE_NATIVE_HEADERS, it is recommended to
-    include module JNI before any call to add_jar. The produced target for native
-    headers can then be used to compile C/C++ sources with command
-    target_link_libraries.
+If the target is a JNI library, utilize the following commands to
+create a JNI symbolic link:
 
+.. code-block:: cmake
 
-::
+  set(CMAKE_JNI_TARGET TRUE)
+  add_jar(shibboleet shibbotleet.java VERSION 1.2.0)
+  install_jar(shibboleet ${LIB_INSTALL_DIR}/shibboleet)
+  install_jni_symlink(shibboleet ${JAVA_LIB_INSTALL_DIR})
 
-       find_package(JNI)
-       add_jar(foo foo.java GENERATE_NATIVE_HEADERS foo-native)
-       add_library(bar bar.cpp)
-       target_link_libraries(bar PRIVATE foo-native)
+If a single target needs to produce more than one jar from its
+java source code, to prevent the accumulation of duplicate class
+files in subsequent jars, set/reset ``CMAKE_JAR_CLASSES_PREFIX`` prior
+to calling the ``add_jar()`` function:
 
+.. code-block:: cmake
 
-Target Properties:
+  set(CMAKE_JAR_CLASSES_PREFIX com/redhat/foo)
+  add_jar(foo foo.java)
 
-::
+  set(CMAKE_JAR_CLASSES_PREFIX com/redhat/bar)
+  add_jar(bar bar.java)
 
-   The add_jar() function sets some target properties. You can get these
-   properties with the
-      get_property(TARGET <target_name> PROPERTY <propery_name>)
-   command.
+For an optimum usage of option ``GENERATE_NATIVE_HEADERS``, it is recommended to
+include module JNI before any call to ``add_jar()``. The produced target for
+native headers can then be used to compile C/C++ sources with the
+:command:`target_link_libraries` command.
 
+.. code-block:: cmake
 
+  find_package(JNI)
+  add_jar(foo foo.java GENERATE_NATIVE_HEADERS foo-native)
+  add_library(bar bar.cpp)
+  target_link_libraries(bar PRIVATE foo-native)
 
-::
 
-   INSTALL_FILES      The files which should be installed. This is used by
-                      install_jar().
-   JNI_SYMLINK        The JNI symlink which should be installed.
-                      This is used by install_jni_symlink().
-   JAR_FILE           The location of the jar file so that you can include
-                      it.
-   CLASSDIR           The directory where the class files can be found. For
-                      example to use them with javah.
+Finding JARs
+^^^^^^^^^^^^
 
-::
+.. code-block:: cmake
 
- find_jar(<VAR>
-          name | NAMES name1 [name2 ...]
-          [PATHS path1 [path2 ... ENV var]]
-          [VERSIONS version1 [version2]]
-          [DOC "cache documentation string"]
+  find_jar(<VAR>
+           <name> | NAMES <name1> [<name2>...]
+           [PATHS <path1> [<path2>... ENV <var>]]
+           [VERSIONS <version1> [<version2>]]
+           [DOC "cache documentation string"]
           )
 
 This command is used to find a full path to the named jar.  A cache
-entry named by <VAR> is created to stor the result of this command.
+entry named by ``<VAR>`` is created to store the result of this command.
 If the full path to a jar is found the result is stored in the
 variable and the search will not repeated unless the variable is
-cleared.  If nothing is found, the result will be <VAR>-NOTFOUND, and
-the search will be attempted again next time find_jar is invoked with
+cleared.  If nothing is found, the result will be ``<VAR>-NOTFOUND``, and
+the search will be attempted again next time ``find_jar()`` is invoked with
 the same variable.  The name of the full path to a file that is
-searched for is specified by the names listed after NAMES argument.
-Additional search locations can be specified after the PATHS argument.
+searched for is specified by the names listed after ``NAMES`` argument.
+Additional search locations can be specified after the ``PATHS`` argument.
 If you require special a version of a jar file you can specify it with
-the VERSIONS argument.  The argument after DOC will be used for the
+the ``VERSIONS`` argument.  The argument after ``DOC`` will be used for the
 documentation string in the cache.
 
-::
-
- install_jar(target_name destination)
- install_jar(target_name DESTINATION destination [COMPONENT component])
-
-This command installs the TARGET_NAME files to the given DESTINATION.
-It should be called in the same scope as add_jar() or it will fail.
-
-Target Properties:
-
-::
-
-   The install_jar() function sets the INSTALL_DESTINATION target property
-   on jars so installed. This property holds the DESTINATION as described
-   above, and is used by install_jar_exports(). You can get this property
-   with the
-      get_property(TARGET <target_name> PROPERTY INSTALL_DESTINATION)
-   command.
 
+Javadoc
+^^^^^^^
 
+The ``create_javadoc()`` command can be used to create java documentation
+based on files or packages.  For more details please read the javadoc manpage.
 
-::
-
- install_jni_symlink(target_name destination)
- install_jni_symlink(target_name DESTINATION destination [COMPONENT component])
+There are two main signatures for ``create_javadoc()``.  The first signature
+works with package names on a path with source files.
 
-This command installs the TARGET_NAME JNI symlinks to the given
-DESTINATION.  It should be called in the same scope as add_jar() or it
-will fail.
-
-::
-
- install_jar_exports(TARGETS jars...
-                     [NAMESPACE <namespace>]
-                     FILE <filename>
-                     DESTINATION <dir> [COMPONENT <component>])
-
-This command installs a target export file ``<filename>`` for the named jar
-targets to the given ``DESTINATION``. Its function is similar to that of
-:command:`install(EXPORTS ...)`.
-
-::
-
- export_jars(TARGETS jars...
-             [NAMESPACE <namespace>]
-             FILE <filename>)
-
-This command writes a target export file ``<filename>`` for the named jar
-targets. Its function is similar to that of :command:`export(...)`.
-
-::
+.. code-block:: cmake
 
  create_javadoc(<VAR>
-                PACKAGES pkg1 [pkg2 ...]
+                PACKAGES <pkg1> [<pkg2>...]
                 [SOURCEPATH <sourcepath>]
                 [CLASSPATH <classpath>]
                 [INSTALLPATH <install path>]
@@ -301,80 +246,70 @@ targets. Its function is similar to that of :command:`export(...)`.
                 [VERSION TRUE|FALSE]
                 )
 
-Create java documentation based on files or packages.  For more
-details please read the javadoc manpage.
-
-There are two main signatures for create_javadoc.  The first signature
-works with package names on a path with source files:
-
-::
-
-   Example:
-   create_javadoc(my_example_doc
-     PACKAGES com.example.foo com.example.bar
-     SOURCEPATH "${CMAKE_CURRENT_SOURCE_DIR}"
-     CLASSPATH ${CMAKE_JAVA_INCLUDE_PATH}
-     WINDOWTITLE "My example"
-     DOCTITLE "<h1>My example</h1>"
-     AUTHOR TRUE
-     USE TRUE
-     VERSION TRUE
-   )
+For example:
 
+.. code-block:: cmake
 
+  create_javadoc(my_example_doc
+    PACKAGES com.example.foo com.example.bar
+    SOURCEPATH "${CMAKE_CURRENT_SOURCE_DIR}"
+    CLASSPATH ${CMAKE_JAVA_INCLUDE_PATH}
+    WINDOWTITLE "My example"
+    DOCTITLE "<h1>My example</h1>"
+    AUTHOR TRUE
+    USE TRUE
+    VERSION TRUE
+  )
 
-The second signature for create_javadoc works on a given list of
+The second signature for ``create_javadoc()`` works on a given list of
 files.
 
-::
-
-   create_javadoc(<VAR>
-                  FILES file1 [file2 ...]
-                  [CLASSPATH <classpath>]
-                  [INSTALLPATH <install path>]
-                  [DOCTITLE "the documentation title"]
-                  [WINDOWTITLE "the title of the document"]
-                  [AUTHOR TRUE|FALSE]
-                  [USE TRUE|FALSE]
-                  [VERSION TRUE|FALSE]
-                 )
-
-
-
-Example:
-
-::
+.. code-block:: cmake
+
+  create_javadoc(<VAR>
+                 FILES <file1> [<file2>...]
+                 [CLASSPATH <classpath>]
+                 [INSTALLPATH <install path>]
+                 [DOCTITLE "the documentation title"]
+                 [WINDOWTITLE "the title of the document"]
+                 [AUTHOR TRUE|FALSE]
+                 [USE TRUE|FALSE]
+                 [VERSION TRUE|FALSE]
+                )
 
-   create_javadoc(my_example_doc
-     FILES ${example_SRCS}
-     CLASSPATH ${CMAKE_JAVA_INCLUDE_PATH}
-     WINDOWTITLE "My example"
-     DOCTITLE "<h1>My example</h1>"
-     AUTHOR TRUE
-     USE TRUE
-     VERSION TRUE
-   )
+For example:
 
+.. code-block:: cmake
 
+  create_javadoc(my_example_doc
+    FILES ${example_SRCS}
+    CLASSPATH ${CMAKE_JAVA_INCLUDE_PATH}
+    WINDOWTITLE "My example"
+    DOCTITLE "<h1>My example</h1>"
+    AUTHOR TRUE
+    USE TRUE
+    VERSION TRUE
+  )
 
 Both signatures share most of the options.  These options are the same
 as what you can find in the javadoc manpage.  Please look at the
-manpage for CLASSPATH, DOCTITLE, WINDOWTITLE, AUTHOR, USE and VERSION.
+manpage for ``CLASSPATH``, ``DOCTITLE``, ``WINDOWTITLE``, ``AUTHOR``, ``USE``
+and ``VERSION``.
 
-The documentation will be by default installed to
+If you don't set the ``INSTALLPATH``, then by default the documentation will
+be installed to :
 
 ::
 
    ${CMAKE_INSTALL_PREFIX}/share/javadoc/<VAR>
 
 
+Header Generation
+^^^^^^^^^^^^^^^^^
 
-if you don't set the INSTALLPATH.
-
-::
+.. code-block:: cmake
 
- create_javah(TARGET <target>
-              GENERATED_FILES <VAR>
+ create_javah(TARGET <target> | GENERATED_FILES <VAR>
               CLASSES <class>...
               [CLASSPATH <classpath>...]
               [DEPENDS <depend>...]
@@ -384,55 +319,55 @@ if you don't set the INSTALLPATH.
 Create C header files from java classes. These files provide the connective glue
 that allow your Java and C code to interact.
 
-This command will no longer be supported starting with version 10 of the JDK due
-to the `suppression of javah tool <http://openjdk.java.net/jeps/313>`_.
-Command ``add_jar(GENERATE_NATIVE_HEADERS)`` must be used instead.
+.. deprecated:: 3.11
 
-There are two main signatures for create_javah.  The first signature
-returns generated files through variable specified by GENERATED_FILES option:
+.. note::
 
-::
+  This command will no longer be supported starting with version 10 of the JDK
+  due to the `suppression of javah tool <http://openjdk.java.net/jeps/313>`_.
+  The ``add_jar(GENERATE_NATIVE_HEADERS)`` command should be used instead.
 
-   Example:
-   Create_javah(GENERATED_FILES files_headers
-     CLASSES org.cmake.HelloWorld
-     CLASSPATH hello.jar
-   )
+There are two main signatures for ``create_javah()``.  The first signature
+returns generated files through variable specified by the ``GENERATED_FILES``
+option.  For example:
 
+.. code-block:: cmake
 
+  create_javah(GENERATED_FILES files_headers
+    CLASSES org.cmake.HelloWorld
+    CLASSPATH hello.jar
+  )
 
-The second signature for create_javah creates a target which encapsulates
-header files generation.
-
-::
-
-   Example:
-   Create_javah(TARGET target_headers
-     CLASSES org.cmake.HelloWorld
-     CLASSPATH hello.jar
-   )
+The second signature for ``create_javah()`` creates a target which encapsulates
+header files generation. E.g.
 
+.. code-block:: cmake
 
+  create_javah(TARGET target_headers
+    CLASSES org.cmake.HelloWorld
+    CLASSPATH hello.jar
+  )
 
 Both signatures share same options.
 
- ``CLASSES <class>...``
-   Specifies Java classes used to generate headers.
+``CLASSES <class>...``
+  Specifies Java classes used to generate headers.
 
- ``CLASSPATH <classpath>...``
-   Specifies various paths to look up classes. Here .class files, jar files or targets
-   created by command add_jar can be used.
+``CLASSPATH <classpath>...``
+  Specifies various paths to look up classes. Here .class files, jar files or
+  targets created by command add_jar can be used.
 
- ``DEPENDS <depend>...``
-   Targets on which the javah target depends
+``DEPENDS <depend>...``
+  Targets on which the javah target depends.
 
- ``OUTPUT_NAME <path>``
-   Concatenates the resulting header files for all the classes listed by option CLASSES
-   into <path>. Same behavior as option '-o' of javah tool.
+``OUTPUT_NAME <path>``
+  Concatenates the resulting header files for all the classes listed by option
+  ``CLASSES`` into ``<path>``.  Same behavior as option ``-o`` of javah tool.
 
- ``OUTPUT_DIR <path>``
-   Sets the directory where the header files will be generated. Same behavior as option
-   '-d' of javah tool. If not specified, ${CMAKE_CURRENT_BINARY_DIR} is used as output directory.
+``OUTPUT_DIR <path>``
+  Sets the directory where the header files will be generated.  Same behavior
+  as option ``-d`` of javah tool.  If not specified,
+  :variable:`CMAKE_CURRENT_BINARY_DIR` is used as the output directory.
 #]=======================================================================]
 
 function (__java_copy_file src dest comment)