From ded5df7513e397c4e5cfe13fa34f4e9498cd3200 Mon Sep 17 00:00:00 2001
From: liuzhifu <liuzhifu@espressif.com>
Date: Wed, 7 Sep 2016 20:33:13 +0800
Subject: [PATCH] add wifi api comments

---
 components/esp32/include/esp_event.h | 54 ++++++++++++++++++++++++++++
 components/esp32/include/esp_wifi.h  | 42 ++++++++++++++++++++++
 2 files changed, 96 insertions(+)

diff --git a/components/esp32/include/esp_event.h b/components/esp32/include/esp_event.h
index 04a53636bb..3fac1434f6 100755
--- a/components/esp32/include/esp_event.h
+++ b/components/esp32/include/esp_event.h
@@ -105,10 +105,64 @@ typedef struct {
     system_event_info_t   event_info;    /**< event information */
 } system_event_t;
 
+/**
+  * @brief  Application specified event callback function
+  *
+  * @param  system_event_t *event : event type defined in this file
+  *
+  * @return ESP_OK : succeed
+  * @return others : fail
+  */
 typedef esp_err_t (*system_event_cb_t)(system_event_t *event);
+
+/**
+  * @brief  Set application specified event callback function
+  *
+  * @attention 1. If cb is NULL, means application don't need to handle 
+  *               If cb is not NULL, it will be call when a event is received, after the default event callback is completed
+  *
+  * @param  system_event_cb_t cb : callback
+  *
+  * @return ESP_OK : succeed
+  * @return others : fail
+  */
 system_event_cb_t esp_event_set_cb(system_event_cb_t cb);
+
+/**
+  * @brief  Send a event to event task
+  *
+  * @attention 1. Other task/module, such as TCPIP modudle, can call this API to send a event to event task
+  *               
+  *
+  * @param  system_event_t * event : event
+  *
+  * @return ESP_OK : succeed
+  * @return others : fail
+  */
 esp_err_t esp_event_send(system_event_t * event);
+
+
+/**
+  * @brief  Get the event handler
+  *
+  * @attention : currently this API returns event queue handler, generally this handler is used to 
+  *              
+  *
+  * @param  null
+  *
+  * @return void* : event queue pointer 
+  */
 void* esp_event_get_handler(void);
+
+/**
+  * @brief  Init the event module
+  *         Create the event handler and task
+  *
+  * @param  system_event_cb_t cb : application specified event callback, it can be modified by call esp_event_set_cb
+  *
+  * @return ESP_OK : succeed
+  * @return others : fail
+  */
 esp_err_t esp_event_init(system_event_cb_t cb);
 
 #ifdef __cplusplus
diff --git a/components/esp32/include/esp_wifi.h b/components/esp32/include/esp_wifi.h
index 90ce0743fe..faae0f95ac 100755
--- a/components/esp32/include/esp_wifi.h
+++ b/components/esp32/include/esp_wifi.h
@@ -12,6 +12,48 @@
 // See the License for the specific language governing permissions and
 // limitations under the License.
 
+
+/*               Notes about WiFi Programming
+ *
+ *  The esp32 wifi programming model can be dipcts as following picture:
+ *
+ *
+ *                            default handler              user handler
+ *  -------------             ---------------             ---------------        
+ *  |           |   event     |             | callback or |             |       
+ *  |   tcpip   | --------->  |    event    | ----------> | application |  
+ *  |   stack   |             |     task    |  event      |    task     |
+ *  |-----------|             |-------------|             |-------------|
+ *                                  /|\                          |
+ *                                   |                           |
+ *                            event  |                           |
+ *                                   |                           |
+ *                                   |                           |
+ *                             ---------------                   |
+ *                             |             |                   |
+ *                             | WiFi Driver |/__________________|
+ *                             |             |\     API call
+ *                             |             |
+ *                             |-------------|
+ * 
+ * The wifi driver can be consider as black box, it knows nothing about the high layer code, such as
+ * TCPIP stack, application task, event task etc, all it can do is to receive API call from high laeyer
+ * or post event queue to a specified Queue, which is initilized by API esp_wifi_init(). 
+ *
+ * The event task is a daemon task, which receives events from WiFi driver or from other subsystem, such
+ * as TCPIP stack, event task will call the default callback function on receiving the event. For example,
+ * on receiving event SYSTEM_EVENT_STA_CONNECTED, it will call tcpip_adapter_start() to start the DHCP
+ * client in it's default handler. 
+ *
+ * Application can register it's owner event callback function by API esp_event_init, then the application callback
+ * function will be called after the default callback. Also, if application don't want to excute the callback
+ * in event task, what it need to do is to post the related event to application task in the application callback function.
+ * 
+ * The application task (code) generally mix all these thing together, it call APIs to init the system/wifi and
+ * handle the events when necessary.
+ * 
+ */
+
 #ifndef __ESP_WIFI_H__
 #define __ESP_WIFI_H__
 
-- 
2.40.0