Merge topic 'CheckSymbolExists-doc'

bf2244681b CheckSymbolExists: Add examples for check_symbol_exists
cafaa5883a CheckCXXSymbolExists: Clarify documented role

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

2 files changed, 31 insertions, 8 deletions

diff --git a/Modules/CheckCXXSymbolExists.cmake b/Modules/CheckCXXSymbolExists.cmake
index 2cccd09..b112094 100644
--- a/Modules/CheckCXXSymbolExists.cmake
+++ b/Modules/CheckCXXSymbolExists.cmake
@@ -5,26 +5,27 @@
 CheckCXXSymbolExists
 --------------------
 
-Check if a symbol exists as a function, variable, or macro in C++
+Check if a symbol exists as a function, variable, or macro in ``C++``.
 
-.. command:: CHECK_CXX_SYMBOL_EXISTS
+.. command:: check_cxx_symbol_exists
 
   .. code-block:: cmake
 
-    CHECK_CXX_SYMBOL_EXISTS(<symbol> <files> <variable>)
+    check_cxx_symbol_exists(<symbol> <files> <variable>)
 
   Check that the ``<symbol>`` is available after including given header
   ``<files>`` and store the result in a ``<variable>``.  Specify the list of
   files in one argument as a semicolon-separated list.
-  ``CHECK_CXX_SYMBOL_EXISTS()`` can be used to check in C++ files, as
-  opposed to ``CHECK_SYMBOL_EXISTS()``, which works only for ``C``.
+  ``check_cxx_symbol_exists()`` can be used to check for symbols as seen by
+  the C++ compiler, as opposed to :command:`check_symbol_exists`, which always
+  uses the ``C`` compiler.
 
   If the header files define the symbol as a macro it is considered
   available and assumed to work.  If the header files declare the symbol
   as a function or variable then the symbol must also be available for
-  linking.  If the symbol is a type or enum value it will not be
-  recognized (consider using :module:`CheckTypeSize`
-  or :module:`CheckCXXSourceCompiles`).
+  linking.  If the symbol is a type, enum value, or C++ template it will
+  not be recognized: consider using the :module:`CheckTypeSize`
+  or :module:`CheckCXXSourceCompiles` module instead.
 
 The following variables may be set before calling this macro to modify
 the way the check is run:
@@ -43,6 +44,17 @@ the way the check is run:
   command. See policy :policy:`CMP0075`.
 ``CMAKE_REQUIRED_QUIET``
   execute quietly without messages.
+
+For example:
+
+.. code-block:: cmake
+
+  include(CheckCXXSymbolExists)
+
+  # Check for macro SEEK_SET
+  check_cxx_symbol_exists(SEEK_SET "cstdio" HAVE_SEEK_SET)
+  # Check for function std::fopen
+  check_cxx_symbol_exists(std::fopen "cstdio" HAVE_STD_FOPEN)
 #]=======================================================================]
 
 include_guard(GLOBAL)
diff --git a/Modules/CheckSymbolExists.cmake b/Modules/CheckSymbolExists.cmake
index b9ef808..c2f488a 100644
--- a/Modules/CheckSymbolExists.cmake
+++ b/Modules/CheckSymbolExists.cmake
@@ -45,6 +45,17 @@ the way the check is run:
   command. See policy :policy:`CMP0075`.
 ``CMAKE_REQUIRED_QUIET``
   execute quietly without messages.
+
+For example:
+
+.. code-block:: cmake
+
+  include(CheckSymbolExists)
+
+  # Check for macro SEEK_SET
+  check_symbol_exists(SEEK_SET "stdio.h" HAVE_SEEK_SET)
+  # Check for function fopen
+  check_symbol_exists(fopen "stdio.h" HAVE_FOPEN)
 #]=======================================================================]
 
 include_guard(GLOBAL)