GenerateExportHeader: Reformat docs.

Modules/GenerateExportHeader.cmake

@@ -6,14 +6,11 @@
 #
 # This module provides the function GENERATE_EXPORT_HEADER().
 #
-# The GENERATE_EXPORT_HEADER function can be used to generate a file
+# The ``GENERATE_EXPORT_HEADER`` function can be used to generate a file
 # suitable for preprocessor inclusion which contains EXPORT macros to be
-# used in library classes.
-#
-# GENERATE_EXPORT_HEADER( LIBRARY_TARGET
-#
-# ::
+# used in library classes::
 #
+#    GENERATE_EXPORT_HEADER( LIBRARY_TARGET
 #              [BASE_NAME <base_name>]
 #              [EXPORT_MACRO_NAME <export_macro_name>]
 #              [EXPORT_FILE_NAME <export_file_name>]
@@ -23,20 +20,21 @@
 #              [NO_DEPRECATED_MACRO_NAME <no_deprecated_macro_name>]
 #              [DEFINE_NO_DEPRECATED]
 #              [PREFIX_NAME <prefix_name>]
+#    )
 #
-# )
 #
-# The target properties CXX_VISIBILITY_PRESET and
-# VISIBILITY_INLINES_HIDDEN can be used to add the appropriate compile
-# flags for targets.  See the documentation of those target properties,
-# and the convenience variables CMAKE_CXX_VISIBILITY_PRESET and
-# CMAKE_VISIBILITY_INLINES_HIDDEN.
+# The target properties :prop_tgt:`CXX_VISIBILITY_PRESET <<LANG>_VISIBILITY_PRESET>`
+# and :prop_tgt:`VISIBILITY_INLINES_HIDDEN` can be used to add the appropriate
+# compile flags for targets.  See the documentation of those target properties,
+# and the convenience variables
+# :variable:`CMAKE_CXX_VISIBILITY_PRESET <CMAKE_<LANG>_VISIBILITY_PRESET>` and
+# :variable:`CMAKE_VISIBILITY_INLINES_HIDDEN`.
 #
-# By default GENERATE_EXPORT_HEADER() generates macro names in a file
+# By default ``GENERATE_EXPORT_HEADER()`` generates macro names in a file
 # name determined by the name of the library.  This means that in the
-# simplest case, users of generate_export_header will be equivalent to:
+# simplest case, users of ``GenerateExportHeader`` will be equivalent to:
 #
-# ::
+# .. code-block:: cmake
 #
 #    set(CMAKE_CXX_VISIBILITY_PRESET hidden)
 #    set(CMAKE_VISIBILITY_INLINES_HIDDEN 1)
@@ -49,10 +47,9 @@
 #    )
 #
 #
-#
 # And in the ABI header files:
 #
-# ::
+# .. code-block:: c++
 #
 #    #include "somelib_export.h"
 #    class SOMELIB_EXPORT SomeClass {
@@ -60,17 +57,16 @@
 #    };
 #
 #
-#
 # The CMake fragment will generate a file in the
-# ${CMAKE_CURRENT_BINARY_DIR} called somelib_export.h containing the
-# macros SOMELIB_EXPORT, SOMELIB_NO_EXPORT, SOMELIB_DEPRECATED,
-# SOMELIB_DEPRECATED_EXPORT and SOMELIB_DEPRECATED_NO_EXPORT.  The
+# ``${CMAKE_CURRENT_BINARY_DIR}`` called ``somelib_export.h`` containing the
+# macros ``SOMELIB_EXPORT``, ``SOMELIB_NO_EXPORT``, ``SOMELIB_DEPRECATED``,
+# ``SOMELIB_DEPRECATED_EXPORT`` and ``SOMELIB_DEPRECATED_NO_EXPORT``.  The
 # resulting file should be installed with other headers in the library.
 #
-# The BASE_NAME argument can be used to override the file name and the
-# names used for the macros
+# The ``BASE_NAME`` argument can be used to override the file name and the
+# names used for the macros:
 #
-# ::
+# .. code-block:: cmake
 #
 #    add_library(somelib someclass.cpp)
 #    generate_export_header(somelib
@@ -78,14 +74,14 @@
 #    )
 #
 #
+# Generates a file called ``other_name_export.h`` containing the macros
+# ``OTHER_NAME_EXPORT``, ``OTHER_NAME_NO_EXPORT`` and ``OTHER_NAME_DEPRECATED``
+# etc.
 #
-# Generates a file called other_name_export.h containing the macros
-# OTHER_NAME_EXPORT, OTHER_NAME_NO_EXPORT and OTHER_NAME_DEPRECATED etc.
-#
-# The BASE_NAME may be overridden by specifiying other options in the
+# The ``BASE_NAME`` may be overridden by specifiying other options in the
 # function.  For example:
 #
-# ::
+# .. code-block:: cmake
 #
 #    add_library(somelib someclass.cpp)
 #    generate_export_header(somelib
@@ -93,11 +89,10 @@
 #    )
 #
 #
+# creates the macro ``OTHER_NAME_EXPORT`` instead of ``SOMELIB_EXPORT``, but
+# other macros and the generated file name is as default:
 #
-# creates the macro OTHER_NAME_EXPORT instead of SOMELIB_EXPORT, but
-# other macros and the generated file name is as default.
-#
-# ::
+# .. code-block:: cmake
 #
 #    add_library(somelib someclass.cpp)
 #    generate_export_header(somelib
@@ -105,17 +100,16 @@
 #    )
 #
 #
+# creates the macro ``KDE_DEPRECATED`` instead of ``SOMELIB_DEPRECATED``.
 #
-# creates the macro KDE_DEPRECATED instead of SOMELIB_DEPRECATED.
-#
-# If LIBRARY_TARGET is a static library, macros are defined without
+# If ``LIBRARY_TARGET`` is a static library, macros are defined without
 # values.
 #
 # If the same sources are used to create both a shared and a static
-# library, the uppercased symbol ${BASE_NAME}_STATIC_DEFINE should be
-# used when building the static library
+# library, the uppercased symbol ``${BASE_NAME}_STATIC_DEFINE`` should be
+# used when building the static library:
 #
-# ::
+# .. code-block:: cmake
 #
 #    add_library(shared_variant SHARED ${lib_SRCS})
 #    add_library(static_variant ${lib_SRCS})
@@ -123,16 +117,14 @@
 #    set_target_properties(static_variant PROPERTIES
 #      COMPILE_FLAGS -DLIBSHARED_AND_STATIC_STATIC_DEFINE)
 #
-#
-#
 # This will cause the export macros to expand to nothing when building
 # the static library.
 #
-# If DEFINE_NO_DEPRECATED is specified, then a macro
-# ${BASE_NAME}_NO_DEPRECATED will be defined This macro can be used to
-# remove deprecated code from preprocessor output.
+# If ``DEFINE_NO_DEPRECATED`` is specified, then a macro
+# ``${BASE_NAME}_NO_DEPRECATED`` will be defined This macro can be used to
+# remove deprecated code from preprocessor output:
 #
-# ::
+# .. code-block:: cmake
 #
 #    option(EXCLUDE_DEPRECATED "Exclude deprecated parts of the library" FALSE)
 #    if (EXCLUDE_DEPRECATED)
@@ -141,10 +133,9 @@
 #    generate_export_header(somelib ${NO_BUILD_DEPRECATED})
 #
 #
-#
 # And then in somelib:
 #
-# ::
+# .. code-block:: c++
 #
 #    class SOMELIB_EXPORT SomeClass
 #    {
@@ -154,42 +145,38 @@
 #    #endif
 #    };
 #
-#
-#
-# ::
+# .. code-block:: c++
 #
 #    #ifndef SOMELIB_NO_DEPRECATED
 #    void SomeClass::oldMethod() {  }
 #    #endif
 #
 #
-#
-# If PREFIX_NAME is specified, the argument will be used as a prefix to
+# If ``PREFIX_NAME`` is specified, the argument will be used as a prefix to
 # all generated macros.
 #
 # For example:
 #
-# ::
+# .. code-block:: cmake
 #
 #    generate_export_header(somelib PREFIX_NAME VTK_)
 #
+# Generates the macros ``VTK_SOMELIB_EXPORT`` etc.
 #
+# ::
 #
-# Generates the macros VTK_SOMELIB_EXPORT etc.
-#
-#
-#
-# ADD_COMPILER_EXPORT_FLAGS( [<output_variable>] )
+#    ADD_COMPILER_EXPORT_FLAGS( [<output_variable>] )
 #
-# The ADD_COMPILER_EXPORT_FLAGS function adds -fvisibility=hidden to
-# CMAKE_CXX_FLAGS if supported, and is a no-op on Windows which does not
-# need extra compiler flags for exporting support.  You may optionally
-# pass a single argument to ADD_COMPILER_EXPORT_FLAGS that will be
-# populated with the required CXX_FLAGS required to enable visibility
+# The ``ADD_COMPILER_EXPORT_FLAGS`` function adds ``-fvisibility=hidden`` to
+# :variable:`CMAKE_CXX_FLAGS <CMAKE_<LANG>_FLAGS>` if supported, and is a no-op
+# on Windows which does not need extra compiler flags for exporting support.
+# You may optionally pass a single argument to ``ADD_COMPILER_EXPORT_FLAGS``
+# that will be populated with the ``CXX_FLAGS`` required to enable visibility
 # support for the compiler/architecture in use.
 #
 # This function is deprecated.  Set the target properties
-# CXX_VISIBILITY_PRESET and VISIBILITY_INLINES_HIDDEN instead.
+# :prop_tgt:`CXX_VISIBILITY_PRESET <<LANG>_VISIBILITY_PRESET>` and
+# :prop_tgt:`VISIBILITY_INLINES_HIDDEN` instead.
 
 #=============================================================================
 # Copyright 2011 Stephen Kelly <[email protected]>