esp32: add some implementation comments

components/esp32/hw_random.c

@@ -23,6 +23,14 @@
 
 uint32_t IRAM_ATTR esp_random(void)
 {
+    /* The PRNG which implements WDEV_RANDOM register gets 2 bits
+     * of extra entropy from a hardware randomness source every APB clock cycle.
+     * To make sure entropy is not drained faster than it is added,
+     * this function needs to wait for at least 16 APB clock cycles after reading
+     * previous word. This implementation may actually wait a bit longer
+     * due to extra time spent in arithmetic and branch statements.
+     */
+
     static uint32_t last_ccount = 0;
     uint32_t ccount;
     do {

components/esp32/lib_printf.c

@@ -12,6 +12,18 @@
 // See the License for the specific language governing permissions and
 // limitations under the License.
 
+/**
+ * @file lib_printf.c
+ *
+ * This file contains library-specific printf functions
+ * used by WiFi libraries in the `lib` directory.
+ * These function are used to catch any output which gets printed
+ * by libraries, and redirect it to ESP_LOG macros.
+ *
+ * Eventually WiFi libraries will use ESP_LOG functions internally
+ * and these definitions will be removed.
+ */
+
 #include <stdio.h>
 #include <stdlib.h>
 #include "esp_log.h"

components/esp32/rtc.h

@@ -12,6 +12,18 @@
 // See the License for the specific language governing permissions and
 // limitations under the License.
 
+/**
+ * @file rtc.h
+ * @brief Declarations of APIs provided by librtc.a
+ *
+ * This file is not in the include directory of esp32 component, so it is not
+ * part of the public API. As the source code of librtc.a is gradually moved
+ * into the ESP-IDF, some of these APIs will be exposed to applications.
+ *
+ * For now, only esp_deep_sleep function declared in esp_deepsleep.h
+ * is part of public API.
+ */
+
 #pragma once
 #include <stdint.h>
 #include <stddef.h>