cmake: fix and clean up some module doc comments

The boards, shields, and zephyr_module CMake modules have some issues
in their comments that can be trivially fixed up.

Signed-off-by: Marti Bolivar <marti.bolivar@nordicsemi.no>

cmake/modules/boards.cmake

@@ -26,7 +26,7 @@
 # - BOARD_ROOT:     BOARD_ROOT with ZEPHYR_BASE appended
 #
 # The following targets will be defined when this CMake module completes:
-# - board  : when invoked a list of valid boards will be printed
+# - board: when invoked, a list of valid boards will be printed
 #
 # Required variables:
 # - BOARD: Board name, including any optional revision field, for example: `foo` or `foo@1.0.0`
@@ -39,8 +39,8 @@
 # - ZEPHYR_BOARD_ALIASES: Environment setting pointing to a CMake file
 #                         containing board aliases.
 #
-# Variables set by this module and not mentioned above are considered internal
-# use only and may be removed, renamed, or re-purposed without prior notice.
+# Variables set by this module and not mentioned above are for internal
+# use only, and may be removed, renamed, or re-purposed without prior notice.
 
 include_guard(GLOBAL)
 

cmake/modules/extensions.cmake

@@ -2540,8 +2540,8 @@ endfunction(zephyr_check_cache variable)
 #   zephyr_boilerplate_watch(SOME_BOILERPLATE_VAR)
 #
 # Inform the build system that SOME_BOILERPLATE_VAR, a variable
-# handled in cmake/app/boilerplate.cmake, is now fixed and should no
-# longer be changed.
+# handled in the Zephyr package's boilerplate code, is now fixed and
+# should no longer be changed.
 #
 # This function uses variable_watch() to print a noisy warning
 # if the variable is set after it returns.

cmake/modules/shields.cmake

@@ -6,21 +6,27 @@
 #
 # This module will validate the SHIELD argument.
 #
-# If a shield implementation is not found for one of the specified shields an
-# error will be raised and list of valid shields will be printed.
+# If a shield implementation is not found for one of the specified shields, an
+# error will be raised and a list of valid shields will be printed.
 #
 # Outcome:
 # The following variables will be defined when this module completes:
-# - shield_conf_files: List of shield specific Kconfig fragments
-# - shield_dts_files : List of shield specific devicetree files
-# - SHIELD_AS_LIST   : A CMake list of shields created from SHIELD variable.
+# - shield_conf_files: List of shield-specific Kconfig fragments
+# - shield_dts_files : List of shield-specific devicetree files
+# - SHIELD_AS_LIST   : A CMake list of shields created from the SHIELD variable.
 # - SHIELD_DIRS      : A CMake list of directories which contain shield definitions
 #
+# The following targets will be defined when this CMake module completes:
+# - shields: when invoked, a list of valid shields will be printed
+#
+# If the SHIELD variable is changed after this module completes,
+# a warning will be printed.
+#
 # Optional variables:
 # - BOARD_ROOT: CMake list of board roots containing board implementations
 #
-# Variables set by this module and not mentioned above are considered internal
-# use only and may be removed, renamed, or re-purposed without prior notice.
+# Variables set by this module and not mentioned above are for internal
+# use only, and may be removed, renamed, or re-purposed without prior notice.
 
 include_guard(GLOBAL)
 

cmake/modules/zephyr_module.cmake

@@ -19,8 +19,8 @@ include(python)
 # It looks for: <module>/zephyr/module.yml or
 #               <module>/zephyr/CMakeLists.txt
 # to load the Zephyr module into Zephyr build system.
-# If west is available, it uses `west list` to obtain a list of projects to
-# search for zephyr/module.yml
+# If west is installed, it uses west's APIs to obtain a list of projects to
+# search for zephyr/module.yml from the current workspace's manifest.
 #
 # If the module.yml file specifies that build files are located in a
 # MODULE_EXT_ROOT then the variables: