TestBigEndian, CMAKE_<LANG>_BYTE_ORDER: Update documentation

- Fixed typo in the module description.
- Added examples section highlighting the code migration towards the
  `CMAKE_<LANG>_BYTE_ORDER` variable.
- Documented command similar to other modules.
- Added examples for the `CMAKE_<LANG>_BYTE_ORDER` variable and
  explained when endianness for different languages can be used.

Help/variable/CMAKE_LANG_BYTE_ORDER.rst

@@ -18,3 +18,78 @@ and ``CUDA``.
 If :variable:`CMAKE_OSX_ARCHITECTURES` specifies multiple architectures, the
 value of ``CMAKE_<LANG>_BYTE_ORDER`` is non-empty only if all architectures
 share the same byte order.
+
+Examples
+^^^^^^^^
+
+Example: Checking Endianness
+""""""""""""""""""""""""""""
+
+Checking endianness (byte order) of the target architecture in a CMake
+project, where ``C`` language is one of the enabled languages, and storing
+the result in a variable ``WORDS_BIGENDIAN``:
+
+.. code-block:: cmake
+
+  if(CMAKE_C_BYTE_ORDER STREQUAL "BIG_ENDIAN")
+    set(WORDS_BIGENDIAN TRUE)
+  elseif(CMAKE_C_BYTE_ORDER STREQUAL "LITTLE_ENDIAN")
+    set(WORDS_BIGENDIAN FALSE)
+  else()
+    set(WORDS_BIGENDIAN FALSE)
+    message(WARNING "Endianness could not be determined.")
+  endif()
+
+Or, if the project doesn't have ``C`` language enabled, it can be replaced
+with some other enabled language.  For example, if ``CXX`` is enabled:
+
+.. code-block:: cmake
+
+  if(CMAKE_CXX_BYTE_ORDER STREQUAL "BIG_ENDIAN")
+    set(WORDS_BIGENDIAN TRUE)
+  elseif(CMAKE_CXX_BYTE_ORDER STREQUAL "LITTLE_ENDIAN")
+    set(WORDS_BIGENDIAN FALSE)
+  else()
+    set(WORDS_BIGENDIAN FALSE)
+    message(WARNING "Endianness could not be determined.")
+  endif()
+
+Note, that in most cases this can be simplified by only checking for a
+big-endian target:
+
+.. code-block:: cmake
+
+  if(CMAKE_C_BYTE_ORDER STREQUAL "BIG_ENDIAN")
+    set(WORDS_BIGENDIAN TRUE)
+  else()
+    set(WORDS_BIGENDIAN FALSE)
+  endif()
+
+Example: Per-language Endianness Check
+""""""""""""""""""""""""""""""""""""""
+
+Most of the time, architectures used today are consistent in endianness
+across compilers.  But here's when per-language endianness check can matter:
+
+* Cross-compilation to different architectures (e.g., big-endian embedded
+  system).
+
+* Heterogeneous toolchains where one target architecture is for C language
+  and another target is for different language.
+
+* Static libraries or binaries reused across platforms (e.g., distributing
+  precompiled CUDA kernels).
+
+.. code-block:: cmake
+
+  if(CMAKE_C_BYTE_ORDER)
+    message(STATUS "C byte order: ${CMAKE_C_BYTE_ORDER}")
+  endif()
+
+  if(CMAKE_CXX_BYTE_ORDER)
+    message(STATUS "C++ byte order: ${CMAKE_CXX_BYTE_ORDER}")
+  endif()
+
+  if(CMAKE_CUDA_BYTE_ORDER)
+    message(STATUS "CUDA byte order: ${CMAKE_CUDA_BYTE_ORDER}")
+  endif()

Modules/TestBigEndian.cmake

@@ -7,19 +7,74 @@ TestBigEndian
 
 .. deprecated:: 3.20
 
-  Supserseded by the :variable:`CMAKE_<LANG>_BYTE_ORDER` variable.
+  Superseded by the :variable:`CMAKE_<LANG>_BYTE_ORDER` variable.
 
-Check if the target architecture is big endian or little endian.
+This module provides a command to check the endianness (byte order) of the
+target architecture.
+
+Load this module in a CMake project with:
+
+.. code-block:: cmake
+
+  include(TestBigEndian)
+
+Commands
+^^^^^^^^
+
+This module provides the following command:
 
 .. command:: test_big_endian
 
+  Checks if the target architecture is big-endian or little-endian:
+
   .. code-block:: cmake
 
     test_big_endian(<var>)
 
-  Stores in variable ``<var>`` either 1 or 0 indicating whether the
+  This command stores in variable ``<var>`` either 1 or 0 indicating whether
-  target architecture is big or little endian.
+  the target architecture is big or little endian.
 
+  At least one of the supported languages must be enabled in
+  CMake project when using this command.
+
+  Supported languages are ``C``, ``CXX``.
+
+  .. versionchanged:: 3.20
+    This command is now mainly a wrapper around the
+    :variable:`CMAKE_<LANG>_BYTE_ORDER` where also ``OBJC``, ``OBJCXX``,
+    and ``CUDA`` languages are supported.
+
+Examples
+^^^^^^^^
+
+Example: Checking Endianness
+""""""""""""""""""""""""""""
+
+Checking endianness of the target architecture with this module and storing
+the result in a CMake variable ``WORDS_BIGENDIAN``:
+
+.. code-block:: cmake
+
+  include(TestBigEndian)
+  test_big_endian(WORDS_BIGENDIAN)
+
+Example: Checking Endianness in New Code
+""""""""""""""""""""""""""""""""""""""""
+
+As of CMake 3.20, this module should be replaced with the
+:variable:`CMAKE_<LANG>_BYTE_ORDER` variable.  For example, in a project,
+where ``C`` language is one of the enabled languages:
+
+.. code-block:: cmake
+
+  if(CMAKE_C_BYTE_ORDER STREQUAL "BIG_ENDIAN")
+    set(WORDS_BIGENDIAN TRUE)
+  elseif(CMAKE_C_BYTE_ORDER STREQUAL "LITTLE_ENDIAN")
+    set(WORDS_BIGENDIAN FALSE)
+  else()
+    set(WORDS_BIGENDIAN FALSE)
+    message(WARNING "Endianness could not be determined.")
+  endif()
 #]=======================================================================]
 include_guard()