From 65052dfbdd0cce0f6781b90cd3bac18b5abceee7 Mon Sep 17 00:00:00 2001
From: Frantisek Hrbata <frantisek.hrbata@espressif.com>
Date: Tue, 7 Oct 2025 13:03:56 +0200
Subject: [PATCH] fix(cmakev2/docs): keep only the very basic functions in API

Currently, we include numerous functions in the automatically generated
documentation for the build system API. Let's begin with only the
essential functions and gradually add more to the API based on requests
and actual needs.

Signed-off-by: Frantisek Hrbata <frantisek.hrbata@espressif.com>
---
 tools/cmakev2/build.cmake     | 20 ++++++++++----------
 tools/cmakev2/compat.cmake    |  8 ++++----
 tools/cmakev2/component.cmake |  1 +
 tools/cmakev2/project.cmake   |  4 ++--
 tools/cmakev2/utilities.cmake |  8 ++++----
 5 files changed, 21 insertions(+), 20 deletions(-)

diff --git a/tools/cmakev2/build.cmake b/tools/cmakev2/build.cmake
index d7b57bc215d..aa9e544274f 100644
--- a/tools/cmakev2/build.cmake
+++ b/tools/cmakev2/build.cmake
@@ -146,7 +146,7 @@ function(__get_library_interface_or_die)
     set(${ARG_OUTPUT} ${library_interface} PARENT_SCOPE)
 endfunction()
 
-#[[api
+#[[
 .. cmakev2:function:: idf_library_set_property
 
     .. code-block:: cmake
@@ -192,7 +192,7 @@ function(idf_library_set_property library property value)
                    ${append})
 endfunction()
 
-#[[api
+#[[
 .. cmakev2:function:: idf_library_get_property
 
     .. code-block:: cmake
@@ -257,7 +257,7 @@ function(__dump_library_properties libraries)
     endforeach()
 endfunction()
 
-#[[api
+#[[
 .. cmakev2:function:: idf_build_library
 
     .. code-block:: cmake
@@ -474,7 +474,7 @@ function(idf_build_library library)
     endforeach()
 endfunction()
 
-#[[api
+#[[
 .. cmakev2:function:: idf_build_executable
 
     .. code-block:: cmake
@@ -640,7 +640,7 @@ function(__get_components_metadata)
     set(${ARG_OUTPUT} "${components_json}" PARENT_SCOPE)
 endfunction()
 
-#[[api
+#[[
 .. cmakev2:function:: idf_build_generate_metadata
 
     .. code-block:: cmake
@@ -740,7 +740,7 @@ function(idf_build_generate_metadata executable)
          CONTENT "${project_description_json_templ}")
 endfunction()
 
-#[[api
+#[[
 .. cmakev2:function:: idf_build_binary
 
     .. code-block:: cmake
@@ -835,7 +835,7 @@ function(idf_build_binary executable)
     set_target_properties(${ARG_TARGET} PROPERTIES BINARY_PATH ${ARG_OUTPUT_FILE})
 endfunction()
 
-#[[api
+#[[
 .. cmakev2:function:: idf_sign_binary
 
     .. code-block:: cmake
@@ -936,7 +936,7 @@ function(idf_sign_binary binary)
     set_target_properties(${ARG_TARGET} PROPERTIES BINARY_PATH ${ARG_OUTPUT_FILE})
 endfunction()
 
-#[[api
+#[[
 .. cmakev2:function:: idf_flash_binary
 
     .. code-block:: cmake
@@ -1017,7 +1017,7 @@ function(idf_flash_binary binary)
     endif()
 endfunction()
 
-#[[api
+#[[
 .. cmakev2:function:: idf_check_binary_size
 
     .. code-block:: cmake
@@ -1051,7 +1051,7 @@ function(idf_check_binary_size binary)
     add_dependencies("${binary}" "${binary}_check_size")
 endfunction()
 
-#[[api
+#[[
 .. cmakev2:function:: idf_check_binary_signed
 
     .. code-block:: cmake
diff --git a/tools/cmakev2/compat.cmake b/tools/cmakev2/compat.cmake
index 57f04002bad..5b7e06793c1 100644
--- a/tools/cmakev2/compat.cmake
+++ b/tools/cmakev2/compat.cmake
@@ -137,7 +137,7 @@ function(__get_component_sources)
     set(${ARG_OUTPUT} "${sources}" PARENT_SCOPE)
 endfunction()
 
-#[[api
+#[[
 .. cmakev2:function:: target_linker_script
 
     .. code-block:: cmake
@@ -195,7 +195,7 @@ function(target_linker_script target deptype scriptfiles)
     endforeach()
 endfunction()
 
-#[[api
+#[[
 .. cmakev2:function:: idf_component_optional_requires
 
     .. code-block:: cmake
@@ -282,7 +282,7 @@ function(__init_common_components)
     idf_build_set_property(__COMMON_COMPONENTS_INITIALIZED YES)
 endfunction()
 
-#[[api
+#[[
 .. cmakev2:function:: idf_component_register
 
     .. code-block:: cmake
@@ -500,7 +500,7 @@ function(idf_component_register)
     idf_component_set_property("${COMPONENT_NAME}" COMPONENT_TYPE "${component_type}")
 endfunction()
 
-#[[api
+#[[
 .. cmakev2:function:: idf_build_component
 
     .. code-block:: cmake
diff --git a/tools/cmakev2/component.cmake b/tools/cmakev2/component.cmake
index ced972449e9..81f8ec416f6 100644
--- a/tools/cmakev2/component.cmake
+++ b/tools/cmakev2/component.cmake
@@ -27,6 +27,7 @@ include(kconfig)
         Property value.
 
     *APPEND*
+
         Append the value to the property's current value instead of replacing
         it.
 
diff --git a/tools/cmakev2/project.cmake b/tools/cmakev2/project.cmake
index dce44bd7871..12500aa165b 100644
--- a/tools/cmakev2/project.cmake
+++ b/tools/cmakev2/project.cmake
@@ -544,7 +544,7 @@ function(__init_project_flash_targets)
     endif()
 endfunction()
 
-#[[api
+#[[
 .. cmakev2:macro:: idf_project_init
 
     .. code-block:: cmake
@@ -644,7 +644,7 @@ macro(idf_project_init)
     unset(project_initialized)
 endmacro()
 
-#[[api
+#[[
 .. cmakev2:function:: idf_build_generate_flasher_args
 
     .. code-block:: cmake
diff --git a/tools/cmakev2/utilities.cmake b/tools/cmakev2/utilities.cmake
index 40182486c02..131f58d6c70 100644
--- a/tools/cmakev2/utilities.cmake
+++ b/tools/cmakev2/utilities.cmake
@@ -10,7 +10,7 @@
 # Using these functions has a side effect: the actual origin of the message
 # appears as the first line of the backtrace.
 
-#[[api
+#[[
 .. cmakev2:function:: idf_die
 
     .. code-block:: cmake
@@ -34,7 +34,7 @@ function(idf_die)
     message(FATAL_ERROR " IDF: ${joined}")
 endfunction()
 
-#[[api
+#[[
 .. cmakev2:function:: idf_warn
 
     .. code-block:: cmake
@@ -57,7 +57,7 @@ function(idf_warn)
     message(WARNING " IDF: ${joined}")
 endfunction()
 
-#[[api
+#[[
 .. cmakev2:function:: idf_msg
 
     .. code-block:: cmake
@@ -80,7 +80,7 @@ function(idf_msg)
     message(STATUS " IDF: ${joined}")
 endfunction()
 
-#[[api
+#[[
 .. cmakev2:function:: idf_dbg
 
     .. code-block:: cmake