Add comments to the top of but files generated by script.

Author: suikan4github

src/sdk/mocksdkwrapper.hpp

@@ -1,3 +1,8 @@
+/*
+ * This file is intended to be read from the sdkwrapper.hpp.
+ * The user program must not include this file.
+ */
+
 #if __has_include(<gmock/gmock.h>)
 
 class MockSdkWrapper : public SdkWrapper {

src/sdk/pico_api_alternate_defs.hpp

@@ -1,3 +1,11 @@
+/*
+ * This file is not to be included from the user program.
+ *
+ * Some of the rpp_driver code include this file. The contents
+ * of this file is alternate type definition for Pico SDK.
+ * These types are declared inside pico SDK. So, x86 build cannot use.
+ */
+
 #ifndef PICO_API_ALTERNATE_DEFS_HPP__
 #define PICO_API_ALTERNATE_DEFS_HPP__
 

src/sdk/pico_sdk_apistub.cpp

@@ -1,3 +1,25 @@
+/*
+ * Definition of the Pico SDK API Stub.
+ *
+ * Stubs in this file is weakly bounded. So, if the hardware_xxx or
+ * the pico_xxx library is not linked in the application, the stub
+ * function in this file will be linked.
+ *
+ * There are two purposes.
+ *
+ * The first one to allow programmer not to link the unused library.
+ * For example, assume a program which doesn't use hardware_i2c lib.
+ * While program doesn't use the API inside this library, the
+ * rpp_driver::SdkWrapper class needs the API. On the other hand,
+ * linking all library of Pico SDK just suppress the error message is
+ * nonsense. So, linking stub is the solution for this problem.
+ *
+ * The second purpose is warning for the unlinked API. Assume a
+ * program which doesn't link the hardware_i2c while it is used.
+ * In this case, there is no link error because the weakly bounded
+ * stub API function is linked. To let the programmer know, the
+ * stub function output the error message to the serial port.
+ */
 #include <stdint.h>
 #include <stdlib.h>
 

src/sdk/pico_sdk_headers.h

@@ -1,7 +1,14 @@
-
+/*
+ * Pico SDK has separated directory and files for the prototype definition.
+ * To include all, we gather the include files in this one file.
+ *
+ * This file is dedicated to be read from the sdkwrapper.hpp.
+ *
+ * Not intended to be read from the application program.
+ */
+#include <../../hardware_clocks/include/hardware/clocks.h>
+#include <../../hardware_gpio/include/hardware/gpio.h>
 #include <../../hardware_i2c/include/hardware/i2c.h>
 #include <../../hardware_pio/include/hardware/pio.h>
-#include <../../hardware_gpio/include/hardware/gpio.h>
-#include <../../hardware_clocks/include/hardware/clocks.h>
-#include <../../pico_time/include/pico/time.h>
 #include <../../pico_stdio/include/pico/stdio.h>
+#include <../../pico_time/include/pico/time.h>

src/sdk/scripts/blocks/mocksdkwrapper_preumble.hpp

@@ -1,3 +1,8 @@
+/*
+ * This file is intended to be read from the sdkwrapper.hpp.
+ * The user program must not include this file.
+ */
+
 #if __has_include(<gmock/gmock.h>)
 
 class MockSdkWrapper : public SdkWrapper {

src/sdk/scripts/blocks/pico_api_alternate_defs.hpp

@@ -1,3 +1,11 @@
+/*
+ * This file is not to be included from the user program.
+ *
+ * Some of the rpp_driver code include this file. The contents
+ * of this file is alternate type definition for Pico SDK.
+ * These types are declared inside pico SDK. So, x86 build cannot use.
+ */
+
 #ifndef PICO_API_ALTERNATE_DEFS_HPP__
 #define PICO_API_ALTERNATE_DEFS_HPP__
 

src/sdk/scripts/blocks/pico_sdk_apistub_preumble.cpp

@@ -1,3 +1,25 @@
+/*
+ * Definition of the Pico SDK API Stub.
+ *
+ * Stubs in this file is weakly bounded. So, if the hardware_xxx or
+ * the pico_xxx library is not linked in the application, the stub
+ * function in this file will be linked.
+ *
+ * There are two purposes.
+ *
+ * The first one to allow programmer not to link the unused library.
+ * For example, assume a program which doesn't use hardware_i2c lib.
+ * While program doesn't use the API inside this library, the
+ * rpp_driver::SdkWrapper class needs the API. On the other hand,
+ * linking all library of Pico SDK just suppress the error message is
+ * nonsense. So, linking stub is the solution for this problem.
+ *
+ * The second purpose is warning for the unlinked API. Assume a
+ * program which doesn't link the hardware_i2c while it is used.
+ * In this case, there is no link error because the weakly bounded
+ * stub API function is linked. To let the programmer know, the
+ * stub function output the error message to the serial port.
+ */
 #include <stdint.h>
 #include <stdlib.h>
 

src/sdk/scripts/blocks/sdkwrapper_preumble.hpp

@@ -1,3 +1,17 @@
+/**
+ * @file sdkwrapper.hpp
+ * @brief Wrapper for RasPi Pico SDK API.
+ * @copyright COPYRIGHT 2024 Seiichi Horie
+ * @details
+ * This file is generated by the scripts in the
+ * src/sdk/scripts.
+ * To re-generate, run :
+ * @code
+ * export PICO_SDK_PATH=/your/path/to/sdk
+ * generate_wrapper.sh
+ * @endcode
+ */
+
 #ifndef PICO_DRIVER_SRC_SDK_SDKWRAPPER_HPP_
 #define PICO_DRIVER_SRC_SDK_SDKWRAPPER_HPP_
 

src/sdk/scripts/generate_wrapper.sh

@@ -16,7 +16,7 @@ cp blocks/mocksdkwrapper_preumble.hpp output/mocksdkwrapper.hpp
 cp blocks/pico_sdk_apistub_preumble.cpp  output/pico_sdk_apistub.cpp
 cp blocks/pico_api_alternate_defs.hpp  output/pico_api_alternate_defs.hpp
 # echo "" > output/fffsdkwrapper.hpp
-echo "" > output/pico_sdk_headers.h
+cp blocks/pico_sdk_headers_preumble.hpp output/pico_sdk_headers.h
 echo "" > debug.hpp
 
 # read FILE

src/sdk/sdkwrapper.hpp

@@ -1,3 +1,17 @@
+/**
+ * @file sdkwrapper.hpp
+ * @brief Wrapper for RasPi Pico SDK API.
+ * @copyright COPYRIGHT 2024 Seiichi Horie
+ * @details
+ * This file is generated by the scripts in the
+ * src/sdk/scripts.
+ * To re-generate, run :
+ * @code
+ * export PICO_SDK_PATH=/your/path/to/sdk
+ * generate_wrapper.sh
+ * @endcode
+ */
+
 #ifndef PICO_DRIVER_SRC_SDK_SDKWRAPPER_HPP_
 #define PICO_DRIVER_SRC_SDK_SDKWRAPPER_HPP_