From 951664749bc4a0a82a7cd655df79a70a8e34e95e Mon Sep 17 00:00:00 2001 From: Marti Bolivar Date: Sat, 7 Jan 2023 14:47:42 -0800 Subject: [PATCH] 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 --- cmake/modules/boards.cmake | 6 +++--- cmake/modules/extensions.cmake | 4 ++-- cmake/modules/shields.cmake | 20 +++++++++++++------- cmake/modules/zephyr_module.cmake | 4 ++-- 4 files changed, 20 insertions(+), 14 deletions(-) diff --git a/cmake/modules/boards.cmake b/cmake/modules/boards.cmake index 2ea958c8423..c9c86030693 100644 --- a/cmake/modules/boards.cmake +++ b/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) diff --git a/cmake/modules/extensions.cmake b/cmake/modules/extensions.cmake index 4acfdfdf685..37f3e2643e4 100644 --- a/cmake/modules/extensions.cmake +++ b/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. diff --git a/cmake/modules/shields.cmake b/cmake/modules/shields.cmake index 10055d1750a..77abc4d603b 100644 --- a/cmake/modules/shields.cmake +++ b/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) diff --git a/cmake/modules/zephyr_module.cmake b/cmake/modules/zephyr_module.cmake index 6609061ee03..6d36972264e 100644 --- a/cmake/modules/zephyr_module.cmake +++ b/cmake/modules/zephyr_module.cmake @@ -19,8 +19,8 @@ include(python) # It looks for: /zephyr/module.yml or # /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: