Add script to extract CMake function descriptions (#2422)

Author: will-v-pi

src/cmake/on_device.cmake

@@ -15,16 +15,22 @@ function(pico_get_runtime_output_directory TARGET output_path_name)
     set(${output_path_name} ${output_path} PARENT_SCOPE)
 endfunction()
 
+# pico_add_hex_output(TARGET)
+# \brief\ Generate a hex file for the target
 function(pico_add_hex_output TARGET)
     pico_get_runtime_output_directory(${TARGET} output_path)
     add_custom_command(TARGET ${TARGET} POST_BUILD COMMAND ${CMAKE_OBJCOPY} -Oihex $<TARGET_FILE:${TARGET}> ${output_path}$<IF:$<BOOL:$<TARGET_PROPERTY:${TARGET},OUTPUT_NAME>>,$<TARGET_PROPERTY:${TARGET},OUTPUT_NAME>,$<TARGET_PROPERTY:${TARGET},NAME>>.hex VERBATIM)
 endfunction()
 
+# pico_add_bin_output(TARGET)
+# \brief\ Generate a bin file for the target
 function(pico_add_bin_output TARGET)
     pico_get_runtime_output_directory(${TARGET} output_path)
     add_custom_command(TARGET ${TARGET} POST_BUILD COMMAND ${CMAKE_OBJCOPY} -Obinary $<TARGET_FILE:${TARGET}> ${output_path}$<IF:$<BOOL:$<TARGET_PROPERTY:${TARGET},OUTPUT_NAME>>,$<TARGET_PROPERTY:${TARGET},OUTPUT_NAME>,$<TARGET_PROPERTY:${TARGET},NAME>>.bin VERBATIM)
 endfunction()
 
+# pico_add_dis_output(TARGET)
+# \brief\ Generate a disassembly file for the target
 function(pico_add_dis_output TARGET)
     pico_get_runtime_output_directory(${TARGET} output_path)
 
@@ -45,6 +51,10 @@ function(pico_add_dis_output TARGET)
             )
 endfunction()
 
+# pico_add_extra_outputs(TARGET)
+# \brief_nodesc\ Perform post-build actions for the target
+#
+# Perform picotool processing and add disassembly, hex, bin, map, and uf2 outputs for the target
 function(pico_add_extra_outputs TARGET)
     # Disassembly will be nonsense for encrypted binaries,
     # so disassemble before picotool processing

src/common/pico_binary_info/CMakeLists.txt

@@ -9,11 +9,19 @@ endif()
 
 target_link_libraries(pico_binary_info INTERFACE pico_binary_info_headers)
 
+# pico_set_program_name(TARGET name)
+# \brief\ Set the program name for the target
+#
+# \param\ name The program name to set
 function(pico_set_program_name TARGET name)
     # PICO_BUILD_DEFINE: PICO_PROGRAM_NAME, value passed to pico_set_program_name, type=string, group=pico_binary_info
     target_compile_definitions(${TARGET} PRIVATE -DPICO_PROGRAM_NAME="${name}")
 endfunction()
 
+# pico_set_program_description(TARGET description)
+# \brief\ Set the program description for the target
+#
+# \param\ description The program description to set
 function(pico_set_program_description TARGET description)
     # since this is the command line, we will remove newlines
     string(REPLACE "\n" " " description ${description})
@@ -22,11 +30,19 @@ function(pico_set_program_description TARGET description)
     target_compile_definitions(${TARGET} PRIVATE -DPICO_PROGRAM_DESCRIPTION="${description}")
 endfunction()
 
+# pico_set_program_url(TARGET url)
+# \brief\ Set the program URL for the target
+#
+# \param\ url The program URL to set
 function(pico_set_program_url TARGET url)
     # PICO_BUILD_DEFINE: PICO_PROGRAM_URL, value passed to pico_set_program_url, type=string, group=pico_binary_info
     target_compile_definitions(${TARGET} PRIVATE -DPICO_PROGRAM_URL="${url}")
 endfunction()
 
+# pico_set_program_version(TARGET version)
+# \brief\ Set the program version for the target
+#
+# \param\ version The program version to set
 function(pico_set_program_version TARGET version)
     # PICO_BUILD_DEFINE: PICO_PROGRAM_VERSION_STRING, value passed to pico_set_program_version, type=string, group=pico_binary_info
     target_compile_definitions(${TARGET} PRIVATE -DPICO_PROGRAM_VERSION_STRING="${version}")

src/rp2040/boot_stage2/CMakeLists.txt

@@ -33,7 +33,13 @@ set(PICO_BOOT_STAGE2_DIR "${CMAKE_CURRENT_LIST_DIR}" CACHE INTERNAL "")
 pico_add_library(boot_stage2_headers)
 target_include_directories(boot_stage2_headers SYSTEM INTERFACE ${CMAKE_CURRENT_LIST_DIR}/include)
 
-# by convention the first source file name without extension is used for the binary info name
+# pico_define_boot_stage2(NAME SOURCES)
+# \brief\ Define a boot stage 2 target.
+#
+# By convention the first source file name without extension is used for the binary info name
+#
+# \param\ NAME The name of the boot stage 2 target
+# \param\ SOURCES The source files to link into the boot stage 2
 function(pico_define_boot_stage2 NAME SOURCES)
     add_executable(${NAME}
             ${SOURCES}
@@ -97,7 +103,12 @@ endmacro()
 
 pico_define_boot_stage2(bs2_default ${PICO_DEFAULT_BOOT_STAGE2_FILE})
 
+# pico_clone_default_boot_stage2(NAME)
+# \brief_nodesc\ Clone the default boot stage 2 target.
+#
 # Create a new boot stage 2 target using the default implementation for the current build (PICO_BOARD derived)
+#
+# \param\ NAME The name of the new boot stage 2 target
 function(pico_clone_default_boot_stage2 NAME)
     pico_define_boot_stage2(${NAME} ${PICO_DEFAULT_BOOT_STAGE2_FILE})
 endfunction()

src/rp2350/boot_stage2/CMakeLists.txt

@@ -33,7 +33,13 @@ set(PICO_BOOT_STAGE2_DIR "${CMAKE_CURRENT_LIST_DIR}" CACHE INTERNAL "")
 pico_add_library(boot_stage2_headers)
 target_include_directories(boot_stage2_headers SYSTEM INTERFACE ${CMAKE_CURRENT_LIST_DIR}/include)
 
-# by convention the first source file name without extension is used for the binary info name
+# pico_define_boot_stage2(NAME SOURCES)
+# \brief\ Define a boot stage 2 target.
+#
+# By convention the first source file name without extension is used for the binary info name
+#
+# \param\ NAME The name of the boot stage 2 target
+# \param\ SOURCES The source files to link into the boot stage 2
 function(pico_define_boot_stage2 NAME SOURCES)
     add_executable(${NAME}
             ${SOURCES}
@@ -97,7 +103,12 @@ endmacro()
 
 pico_define_boot_stage2(bs2_default ${PICO_DEFAULT_BOOT_STAGE2_FILE})
 
+# pico_clone_default_boot_stage2(NAME)
+# \brief_nodesc\ Clone the default boot stage 2 target.
+#
 # Create a new boot stage 2 target using the default implementation for the current build (PICO_BOARD derived)
+#
+# \param\ NAME The name of the new boot stage 2 target
 function(pico_clone_default_boot_stage2 NAME)
     pico_define_boot_stage2(${NAME} ${PICO_DEFAULT_BOOT_STAGE2_FILE})
 endfunction()

src/rp2_common/pico_btstack/CMakeLists.txt

@@ -302,9 +302,15 @@ if (EXISTS ${PICO_BTSTACK_PATH}/${BTSTACK_TEST_PATH})
 
     pico_promote_common_scope_vars()
 
-    # Make a GATT header file from a BTstack GATT file
-    # Pass the target library name library type and path to the GATT input file
-    # To add additional directories to the gatt #import path, add them to the end of the argument list.
+    # pico_btstack_make_gatt_header(TARGET_LIB TARGET_TYPE GATT_FILE)
+    # \brief\ Make a GATT header file from a BTstack GATT file.
+    #
+    # Pass the target library name, library type, and path to the GATT input file.
+    # To add additional directories to the gatt import path, add them to the end of the argument list.
+    #
+    # \param\ TARGET_LIB The target library name
+    # \param\ TARGET_TYPE The target library type
+    # \param\ GATT_FILE The path to the GATT input file
     function(pico_btstack_make_gatt_header TARGET_LIB TARGET_TYPE GATT_FILE)
             find_package (Python3 REQUIRED COMPONENTS Interpreter)
             get_filename_component(GATT_NAME "${GATT_FILE}" NAME_WE)

src/rp2_common/pico_cyw43_driver/CMakeLists.txt

@@ -131,16 +131,22 @@ if (EXISTS ${PICO_CYW43_DRIVER_PATH}/${CYW43_DRIVER_TEST_FILE})
                 )
     endif()
 
-    # Set an ip address in a compile definition
-    # target name, target type, compile definition name to set then address in a string
-    # This can be used to set the following compile definitions
-    # CYW43_DEFAULT_IP_STA_ADDRESS
-    # CYW43_DEFAULT_IP_STA_GATEWAY
-    # CYW43_DEFAULT_IP_AP_ADDRESS
-    # CYW43_DEFAULT_IP_AP_GATEWAY
-    # CYW43_DEFAULT_IP_MASK
-    # CYW43_DEFAULT_IP_DNS
+    # pico_configure_ip4_address(TARGET_LIB TARGET_TYPE DEF_NAME IP_ADDRESS_STR)
+    # \brief\ Set an ip address in a compile definition
+    #
+    # This can be used to set the following compile definitions;
+    # CYW43_DEFAULT_IP_STA_ADDRESS;
+    # CYW43_DEFAULT_IP_STA_GATEWAY;
+    # CYW43_DEFAULT_IP_AP_ADDRESS;
+    # CYW43_DEFAULT_IP_AP_GATEWAY;
+    # CYW43_DEFAULT_IP_MASK;
+    # CYW43_DEFAULT_IP_DNS;
     # e.g. pico_configure_ip4_address(picow_tcpip_server_background PRIVATE CYW43_DEFAULT_IP_STA_ADDRESS "10.3.15.204")
+    #
+    # \param\ TARGET_LIB The target library to set the ip address for
+    # \param\ TARGET_TYPE The type of target library
+    # \param\ DEF_NAME The name of the compile definition to set
+    # \param\ IP_ADDRESS_STR The ip address to set
     function(pico_configure_ip4_address TARGET_LIB TARGET_TYPE DEF_NAME IP_ADDRESS_STR)
             string(REGEX MATCHALL "[0-9]+" IP_ADDRESS_LIST ${IP_ADDRESS_STR})
             list(LENGTH IP_ADDRESS_LIST IP_ADDRESS_COMPONENT_COUNT)

src/rp2_common/pico_lwip/tools/CMakeLists.txt

@@ -1,5 +1,13 @@
-# Compile the http content into a source file "pico_fsdata.inc" in a format suitable for the lwip httpd server
-# Pass the target library name library type and the list of httpd content
+# pico_set_lwip_httpd_content(TARGET_LIB TARGET_TYPE HTTPD_FILES...)
+# \ingroup\ pico_lwip
+# \brief_nodesc\ Compile the http content into a source file for lwip.
+#
+# Compile the http content into a source file "pico_fsdata.inc" in a format suitable for the lwip httpd server.
+# Pass the target library name, library type, and the list of httpd content files to compile.
+#
+# \param\ TARGET_LIB The target library name
+# \param\ TARGET_TYPE The type of the target library
+# \param\ HTTPD_FILES The list of httpd content files to compile
 function(pico_set_lwip_httpd_content TARGET_LIB TARGET_TYPE)
     find_package (Python3 REQUIRED COMPONENTS Interpreter)
     set(HTTPD_CONTENT_BINARY_DIR "${CMAKE_CURRENT_BINARY_DIR}/generated")

src/rp2_common/pico_runtime/CMakeLists.txt

@@ -51,22 +51,26 @@ elseif (PICO_C_COMPILER_IS_CLANG)
    # target_link_options(pico_runtime INTERFACE "-nostdlib")
 endif()
 
-# pico_minimize_runtime((INCLUDE ...) (EXCLUDE ...))
+# pico_minimize_runtime(TARGET [INCLUDE ...] [EXCLUDE ...])
+# \brief\ Minimize the runtime components for the target
 #
 # INCLUDE/EXCLUDE can contain any of the following (all defaulting to not included)
 #
-# DEFAULT_ALARM_POOL    - default alarm pool setup
-# PRINTF                - full printf support
-# PRINTF_MINIMAL        - printf support without the following
-# PRINTF_FLOAT          - to control float support if printf is enabled
-# PRINTF_EXPONENTIAL
-# PRINTF_LONG_LONG
-# PRINTF_PTRDIFF_T
-# FLOAT                 - support for single-precision floating point
-# DOUBLE                - support for double-precision floating point
-# FPGA_CHECK            - checks for FPGA which allows Raspberry Pi to run your binary on FPGA
-# PANIC                 - default panic impl which brings in stdio
-# AUTO_INIT_MUTEX       - auto init mutexes; without this you get no printf mutex either               -
+# DEFAULT_ALARM_POOL    - default alarm pool setup;
+# PRINTF                - full printf support;
+# PRINTF_MINIMAL        - printf support without the following;
+# PRINTF_FLOAT          - to control float support if printf is enabled;
+# PRINTF_EXPONENTIAL    - to control exponential support if printf is enabled;
+# PRINTF_LONG_LONG      - to control long long support if printf is enabled;
+# PRINTF_PTRDIFF_T      - to control ptrdiff_t support if printf is enabled;
+# FLOAT                 - support for single-precision floating point;
+# DOUBLE                - support for double-precision floating point;
+# FPGA_CHECK            - checks for FPGA which allows Raspberry Pi to run your binary on FPGA;
+# PANIC                 - default panic impl which brings in stdio;
+# AUTO_INIT_MUTEX       - auto init mutexes, without this you get no printf mutex either;
+#
+# \param\ INCLUDE The items to include
+# \param\ EXCLUDE The items to exclude
 function(pico_minimize_runtime TARGET)
     set(ALL_ITEMS
             DEFAULT_ALARM_POOL

src/rp2_common/pico_standard_link/CMakeLists.txt

@@ -5,6 +5,10 @@ if (NOT TARGET pico_standard_link)
         target_link_libraries(pico_standard_link INTERFACE boot_stage2_headers)
     endif()
 
+    # pico_add_link_depend(TARGET dependency)
+    # \brief\ Add a link time dependency to the target
+    #
+    # \param\ dependency The dependency to add
     function(pico_add_link_depend TARGET dependency)
         get_target_property(target_type ${TARGET} TYPE)
         if (${target_type} STREQUAL "INTERFACE_LIBRARY")
@@ -21,11 +25,18 @@ if (NOT TARGET pico_standard_link)
         set_target_properties(${TARGET} PROPERTIES ${PROP} "${_LINK_DEPENDS}")
     endfunction()
 
-    # need this because cmake does not appear to have a way to override an INTERFACE variable
+    # pico_set_linker_script(TARGET LDSCRIPT)
+    # \brief\ Set the linker script for the target
+    #
+    # \param\ LDSCRIPT Full path to the linker script to set
     function(pico_set_linker_script TARGET LDSCRIPT)
         set_target_properties(${TARGET} PROPERTIES PICO_TARGET_LINKER_SCRIPT ${LDSCRIPT})
     endfunction()
 
+    # pico_set_binary_type(TARGET TYPE)
+    # \brief\ Set the binary type for the target
+    #
+    # \param\ TYPE The binary type to set
     function(pico_set_binary_type TARGET TYPE)
         set_target_properties(${TARGET} PROPERTIES PICO_TARGET_BINARY_TYPE ${TYPE})
     endfunction()

src/rp2_common/pico_stdio/CMakeLists.txt

@@ -26,18 +26,34 @@ if (NOT TARGET pico_stdio)
         pico_mirrored_target_link_libraries(pico_stdio INTERFACE pico_printf)
     endif()
 
+    # pico_enable_stdio_uart(TARGET ENABLED)
+    # \brief\ Enable stdio UART for the target
+    #
+    # \param\ ENABLED Whether to enable stdio UART
     function(pico_enable_stdio_uart TARGET ENABLED)
         set_target_properties(${TARGET} PROPERTIES PICO_TARGET_STDIO_UART ${ENABLED})
     endfunction()
 
+    # pico_enable_stdio_usb(TARGET ENABLED)
+    # \brief\ Enable stdio USB for the target
+    #
+    # \param\ ENABLED Whether to enable stdio USB
     function(pico_enable_stdio_usb TARGET ENABLED)
         set_target_properties(${TARGET} PROPERTIES PICO_TARGET_STDIO_USB ${ENABLED})
     endfunction()
 
+    # pico_enable_stdio_semihosting(TARGET ENABLED)
+    # \brief\ Enable stdio semi-hosting for the target
+    #
+    # \param\ ENABLED Whether to enable stdio semi-hosting
     function(pico_enable_stdio_semihosting TARGET ENABLED)
         set_target_properties(${TARGET} PROPERTIES PICO_TARGET_STDIO_SEMIHOSTING ${ENABLED})
     endfunction()
 
+    # pico_enable_stdio_rtt(TARGET ENABLED)
+    # \brief\ Enable stdio RTT for the target
+    #
+    # \param\ ENABLED Whether to enable stdio RTT
     function(pico_enable_stdio_rtt TARGET ENABLED)
         set_target_properties(${TARGET} PROPERTIES PICO_TARGET_STDIO_RTT ${ENABLED})
     endfunction()