From 56d55c88cc349e9d624b778b51d6240baf9f4a26 Mon Sep 17 00:00:00 2001
From: Peter Kokot <peterkokot@gmail.com>
Date: Wed, 14 May 2025 18:44:38 +0200
Subject: [PATCH] UseEcos: Extend documentation

- Added intro code block showing how to load this module.
- Synced descriptions.
- Used "commands" instead of "macros".
- Added example description.
---
 Modules/UseEcos.cmake | 63 ++++++++++++++++++++++++++++---------------
 1 file changed, 41 insertions(+), 22 deletions(-)

diff --git a/Modules/UseEcos.cmake b/Modules/UseEcos.cmake
index 1942ddd78b..e080d8b371 100644
--- a/Modules/UseEcos.cmake
+++ b/Modules/UseEcos.cmake
@@ -5,87 +5,102 @@
 UseEcos
 -------
 
-This module defines variables and macros required to build eCos application.
+This module defines variables and provides commands required to build an eCos
+application.
 
-Macros
-^^^^^^
+Load this module in CMake project with:
 
-This module defines the following macros:
+.. code-block:: cmake
+
+  include(UseEcos)
+
+Commands
+^^^^^^^^
+
+This module provides the following commands:
+
+Building an eCos Application
+""""""""""""""""""""""""""""
 
 .. command:: ecos_add_include_directories
 
+  Adds the eCos include directories for the current ``CMakeLists.txt`` file:
+
   .. code-block:: cmake
 
     ecos_add_include_directories()
 
-  Adds the eCos include directories for the current `CMakeLists.txt` file.
-
 .. command:: ecos_adjust_directory
 
+  Adjusts the paths of given source files:
+
   .. code-block:: cmake
 
     ecos_adjust_directory(<var> <sources>...)
 
-  Adjusts the paths of given source files ``<sources>...`` and stores them into
-  a result variable named ``<var>``.
+  This command modifies the paths of the source files ``<sources>...`` to
+  make them suitable for use with ``ecos_add_executable()``, and stores them
+  in the variable ``<var>``.
 
   ``<var>``
     Result variable name holding a new list of source files with adjusted paths.
   ``<sources>...``
     A list of relative or absolute source files to adjust their paths.
 
-  Use this macro when the actual sources are located one level upwards. A
+  Use this command when the actual sources are located one level upwards. A
   ``../`` has to be prepended in front of every source file that is given as a
   relative path.
 
 .. command:: ecos_add_executable
 
+  Creates an eCos application executable:
+
   .. code-block:: cmake
 
     ecos_add_executable(<name> <sources>...)
 
-  Creates an eCos application executable.
-
   ``<name>``
     The name of the executable.
   ``<sources>...``
     A list of all source files, where the path has been adjusted beforehand by
     calling the ``ecos_adjust_directory()``.
 
-  This macro also sets the ``ECOS_DEFINITIONS`` local variable, holding some
+  This command also sets the ``ECOS_DEFINITIONS`` local variable, holding some
   common compile definitions.
 
-Macros for selecting the toolchain:
+Selecting the Toolchain
+"""""""""""""""""""""""
 
 .. command:: ecos_use_arm_elf_tools
 
+  Enables the ARM ELF toolchain for the directory where it is called:
+
   .. code-block:: cmake
 
     ecos_use_arm_elf_tools()
 
-  Enables the ARM ELF toolchain for the directory where it is called. Use this
-  macro, when compiling for the xscale processor.
+  Use this command, when compiling for the xscale processor.
 
 .. command:: ecos_use_i386_elf_tools
 
+  Enables the i386 ELF toolchain for the directory where it is called:
+
   .. code-block:: cmake
 
     ecos_use_i386_elf_tools()
 
-  Enables the i386 ELF toolchain for the directory where it is called.
-
 .. command:: ecos_use_ppc_eabi_tools
 
+  Enables the PowerPC toolchain for the directory where it is called:
+
   .. code-block:: cmake
 
     ecos_use_ppc_eabi_tools()
 
-  Enables the PowerPC toolchain for the directory where it is called.
-
 Variables
 ^^^^^^^^^
 
-Module also defines the following variables:
+This module also defines the following variables:
 
 ``ECOSCONFIG_EXECUTABLE``
   Cache variable that contains a path to the ``ecosconfig`` executable (the eCos
@@ -99,9 +114,13 @@ Module also defines the following variables:
 Examples
 ^^^^^^^^
 
-.. code-block:: cmake
+The following example demonstrates defining an eCos executable target in a
+project that follows the common eCos convention of listing source files in
+a ``ProjectSources.txt`` file, located one directory above the current
+``CMakeLists.txt``:
 
-  # CMakeLists.txt
+.. code-block:: cmake
+  :caption: ``CMakeLists.txt``
 
   include(UseEcos)