Merge topic 'doc-FortranCInterface-variables'

4f3f75a2 FortranCInterface: Document mangling result variables publicly
47f24cbc FortranCInterface: Improve documentation formatting and organization
9d1f40cc FortranCInterface: Convert docs to a bracket comment

1 files changed, 187 insertions, 126 deletions

diff --git a/Modules/FortranCInterface.cmake b/Modules/FortranCInterface.cmake
index 70c3fd7..c12dd4c 100644
--- a/Modules/FortranCInterface.cmake
+++ b/Modules/FortranCInterface.cmake
@@ -1,129 +1,190 @@
-#.rst:
-# FortranCInterface
-# -----------------
-#
-# Fortran/C Interface Detection
-#
-# This module automatically detects the API by which C and Fortran
-# languages interact.  Variables indicate if the mangling is found:
-#
-# ::
-#
-#    FortranCInterface_GLOBAL_FOUND = Global subroutines and functions
-#    FortranCInterface_MODULE_FOUND = Module subroutines and functions
-#                                     (declared by "MODULE PROCEDURE")
-#
-# A function is provided to generate a C header file containing macros
-# to mangle symbol names:
-#
-# ::
-#
-#    FortranCInterface_HEADER(<file>
-#                             [MACRO_NAMESPACE <macro-ns>]
-#                             [SYMBOL_NAMESPACE <ns>]
-#                             [SYMBOLS [<module>:]<function> ...])
-#
-# It generates in <file> definitions of the following macros:
-#
-# ::
-#
-#    #define FortranCInterface_GLOBAL (name,NAME) ...
-#    #define FortranCInterface_GLOBAL_(name,NAME) ...
-#    #define FortranCInterface_MODULE (mod,name, MOD,NAME) ...
-#    #define FortranCInterface_MODULE_(mod,name, MOD,NAME) ...
-#
-# These macros mangle four categories of Fortran symbols, respectively:
-#
-# ::
-#
-#    - Global symbols without '_': call mysub()
-#    - Global symbols with '_'   : call my_sub()
-#    - Module symbols without '_': use mymod; call mysub()
-#    - Module symbols with '_'   : use mymod; call my_sub()
-#
-# If mangling for a category is not known, its macro is left undefined.
-# All macros require raw names in both lower case and upper case.  The
-# MACRO_NAMESPACE option replaces the default "FortranCInterface_"
-# prefix with a given namespace "<macro-ns>".
-#
-# The SYMBOLS option lists symbols to mangle automatically with C
-# preprocessor definitions:
-#
-# ::
-#
-#    <function>          ==> #define <ns><function> ...
-#    <module>:<function> ==> #define <ns><module>_<function> ...
-#
-# If the mangling for some symbol is not known then no preprocessor
-# definition is created, and a warning is displayed.  The
-# SYMBOL_NAMESPACE option prefixes all preprocessor definitions
-# generated by the SYMBOLS option with a given namespace "<ns>".
-#
-# Example usage:
-#
-# ::
-#
-#    include(FortranCInterface)
-#    FortranCInterface_HEADER(FC.h MACRO_NAMESPACE "FC_")
-#
-# This creates a "FC.h" header that defines mangling macros FC_GLOBAL(),
-# FC_GLOBAL_(), FC_MODULE(), and FC_MODULE_().
-#
-# Example usage:
-#
-# ::
-#
-#    include(FortranCInterface)
-#    FortranCInterface_HEADER(FCMangle.h
-#                             MACRO_NAMESPACE "FC_"
-#                             SYMBOL_NAMESPACE "FC_"
-#                             SYMBOLS mysub mymod:my_sub)
-#
-# This creates a "FCMangle.h" header that defines the same FC_*()
-# mangling macros as the previous example plus preprocessor symbols
-# FC_mysub and FC_mymod_my_sub.
-#
-# Another function is provided to verify that the Fortran and C/C++
-# compilers work together:
-#
-# ::
-#
-#    FortranCInterface_VERIFY([CXX] [QUIET])
-#
-# It tests whether a simple test executable using Fortran and C (and C++
-# when the CXX option is given) compiles and links successfully.  The
-# result is stored in the cache entry FortranCInterface_VERIFIED_C (or
-# FortranCInterface_VERIFIED_CXX if CXX is given) as a boolean.  If the
-# check fails and QUIET is not given the function terminates with a
-# FATAL_ERROR message describing the problem.  The purpose of this check
-# is to stop a build early for incompatible compiler combinations.  The
-# test is built in the Release configuration.
-#
-# FortranCInterface is aware of possible GLOBAL and MODULE manglings for
-# many Fortran compilers, but it also provides an interface to specify
-# new possible manglings.  Set the variables
-#
-# ::
-#
-#    FortranCInterface_GLOBAL_SYMBOLS
-#    FortranCInterface_MODULE_SYMBOLS
-#
-# before including FortranCInterface to specify manglings of the symbols
-# "MySub", "My_Sub", "MyModule:MySub", and "My_Module:My_Sub".  For
-# example, the code:
-#
-# ::
-#
-#    set(FortranCInterface_GLOBAL_SYMBOLS mysub_ my_sub__ MYSUB_)
-#      #                                  ^^^^^  ^^^^^^   ^^^^^
-#    set(FortranCInterface_MODULE_SYMBOLS
-#        __mymodule_MOD_mysub __my_module_MOD_my_sub)
-#      #   ^^^^^^^^     ^^^^^   ^^^^^^^^^     ^^^^^^
-#    include(FortranCInterface)
-#
-# tells FortranCInterface to try given GLOBAL and MODULE manglings.
-# (The carets point at raw symbol names for clarity in this example but
-# are not needed.)
+#[=======================================================================[.rst:
+FortranCInterface
+-----------------
+
+Fortran/C Interface Detection
+
+This module automatically detects the API by which C and Fortran
+languages interact.
+
+Module Variables
+^^^^^^^^^^^^^^^^
+
+Variables that indicate if the mangling is found:
+
+``FortranCInterface_GLOBAL_FOUND``
+  Global subroutines and functions.
+
+``FortranCInterface_MODULE_FOUND``
+  Module subroutines and functions (declared by "MODULE PROCEDURE").
+
+This module also provides the following variables to specify
+the detected mangling, though a typical use case does not need
+to reference them and can use the `Module Functions`_ below.
+
+``FortranCInterface_GLOBAL_PREFIX``
+  Prefix for a global symbol without an underscore.
+
+``FortranCInterface_GLOBAL_SUFFIX``
+  Suffix for a global symbol without an underscore.
+
+``FortranCInterface_GLOBAL_CASE``
+  The case for a global symbol without an underscore,
+  either ``UPPER`` or ``LOWER``.
+
+``FortranCInterface_GLOBAL__PREFIX``
+  Prefix for a global symbol with an underscore.
+
+``FortranCInterface_GLOBAL__SUFFIX``
+  Suffix for a global symbol with an underscore.
+
+``FortranCInterface_GLOBAL__CASE``
+  The case for a global symbol with an underscore,
+  either ``UPPER`` or ``LOWER``.
+
+``FortranCInterface_MODULE_PREFIX``
+  Prefix for a module symbol without an underscore.
+
+``FortranCInterface_MODULE_MIDDLE``
+  Middle of a module symbol without an underscore that appears
+  between the name of the module and the name of the symbol.
+
+``FortranCInterface_MODULE_SUFFIX``
+  Suffix for a module symbol without an underscore.
+
+``FortranCInterface_MODULE_CASE``
+  The case for a module symbol without an underscore,
+  either ``UPPER`` or ``LOWER``.
+
+``FortranCInterface_MODULE__PREFIX``
+  Prefix for a module symbol with an underscore.
+
+``FortranCInterface_MODULE__MIDDLE``
+  Middle of a module symbol with an underscore that appears
+  between the name of the module and the name of the symbol.
+
+``FortranCInterface_MODULE__SUFFIX``
+  Suffix for a module symbol with an underscore.
+
+``FortranCInterface_MODULE__CASE``
+  The case for a module symbol with an underscore,
+  either ``UPPER`` or ``LOWER``.
+
+Module Functions
+^^^^^^^^^^^^^^^^
+
+.. command:: FortranCInterface_HEADER
+
+  The ``FortranCInterface_HEADER`` function is provided to generate a
+  C header file containing macros to mangle symbol names::
+
+    FortranCInterface_HEADER(<file>
+                             [MACRO_NAMESPACE <macro-ns>]
+                             [SYMBOL_NAMESPACE <ns>]
+                             [SYMBOLS [<module>:]<function> ...])
+
+  It generates in ``<file>`` definitions of the following macros::
+
+     #define FortranCInterface_GLOBAL (name,NAME) ...
+     #define FortranCInterface_GLOBAL_(name,NAME) ...
+     #define FortranCInterface_MODULE (mod,name, MOD,NAME) ...
+     #define FortranCInterface_MODULE_(mod,name, MOD,NAME) ...
+
+  These macros mangle four categories of Fortran symbols, respectively:
+
+  * Global symbols without '_': ``call mysub()``
+  * Global symbols with '_'   : ``call my_sub()``
+  * Module symbols without '_': ``use mymod; call mysub()``
+  * Module symbols with '_'   : ``use mymod; call my_sub()``
+
+  If mangling for a category is not known, its macro is left undefined.
+  All macros require raw names in both lower case and upper case.
+
+  The options are:
+
+  ``MACRO_NAMESPACE``
+    Replace the default ``FortranCInterface_`` prefix with a given
+    namespace ``<macro-ns>``.
+
+  ``SYMBOLS``
+    List symbols to mangle automatically with C preprocessor definitions::
+
+      <function>          ==> #define <ns><function> ...
+      <module>:<function> ==> #define <ns><module>_<function> ...
+
+    If the mangling for some symbol is not known then no preprocessor
+    definition is created, and a warning is displayed.
+
+  ``SYMBOL_NAMESPACE``
+    Prefix all preprocessor definitions generated by the ``SYMBOLS``
+    option with a given namespace ``<ns>``.
+
+.. command:: FortranCInterface_VERIFY
+
+  The ``FortranCInterface_VERIFY`` function is provided to verify
+  that the Fortran and C/C++ compilers work together::
+
+    FortranCInterface_VERIFY([CXX] [QUIET])
+
+  It tests whether a simple test executable using Fortran and C (and C++
+  when the CXX option is given) compiles and links successfully.  The
+  result is stored in the cache entry ``FortranCInterface_VERIFIED_C``
+  (or ``FortranCInterface_VERIFIED_CXX`` if ``CXX`` is given) as a boolean.
+  If the check fails and ``QUIET`` is not given the function terminates with a
+  fatal error message describing the problem.  The purpose of this check
+  is to stop a build early for incompatible compiler combinations.  The
+  test is built in the ``Release`` configuration.
+
+Example Usage
+^^^^^^^^^^^^^
+
+.. code-block:: cmake
+
+   include(FortranCInterface)
+   FortranCInterface_HEADER(FC.h MACRO_NAMESPACE "FC_")
+
+This creates a "FC.h" header that defines mangling macros ``FC_GLOBAL()``,
+``FC_GLOBAL_()``, ``FC_MODULE()``, and ``FC_MODULE_()``.
+
+.. code-block:: cmake
+
+   include(FortranCInterface)
+   FortranCInterface_HEADER(FCMangle.h
+                            MACRO_NAMESPACE "FC_"
+                            SYMBOL_NAMESPACE "FC_"
+                            SYMBOLS mysub mymod:my_sub)
+
+This creates a "FCMangle.h" header that defines the same ``FC_*()``
+mangling macros as the previous example plus preprocessor symbols
+``FC_mysub`` and ``FC_mymod_my_sub``.
+
+Additional Manglings
+^^^^^^^^^^^^^^^^^^^^
+
+FortranCInterface is aware of possible ``GLOBAL`` and ``MODULE`` manglings
+for many Fortran compilers, but it also provides an interface to specify
+new possible manglings.  Set the variables::
+
+   FortranCInterface_GLOBAL_SYMBOLS
+   FortranCInterface_MODULE_SYMBOLS
+
+before including FortranCInterface to specify manglings of the symbols
+``MySub``, ``My_Sub``, ``MyModule:MySub``, and ``My_Module:My_Sub``.
+For example, the code:
+
+.. code-block:: cmake
+
+   set(FortranCInterface_GLOBAL_SYMBOLS mysub_ my_sub__ MYSUB_)
+     #                                  ^^^^^  ^^^^^^   ^^^^^
+   set(FortranCInterface_MODULE_SYMBOLS
+       __mymodule_MOD_mysub __my_module_MOD_my_sub)
+     #   ^^^^^^^^     ^^^^^   ^^^^^^^^^     ^^^^^^
+   include(FortranCInterface)
+
+tells FortranCInterface to try given ``GLOBAL`` and ``MODULE`` manglings.
+(The carets point at raw symbol names for clarity in this example but
+are not needed.)
+#]=======================================================================]
 
 #=============================================================================
 # Copyright 2008-2009 Kitware, Inc.