【添加】一些必要的函数注释

Signed-off-by: liuxianliang <liuxianliang@rt-thread.com>

class/air720/ppp_device_air720.c

@@ -66,16 +66,11 @@ static struct ppp_device_ops air720_ops =
     .prepare = ppp_air720_prepare,
 };
 
-/*
+/**
  * register air720 into ppp_device
  *
- * @parameter   RT_NULL
- *
- *
- *
- *
- * @return  ppp_device function piont
- *
+ * @return  =0:   ppp_device register successfully
+ *          <0:   ppp_device register failed
  */
 int ppp_air720_register(void)
 {

class/m6312/ppp_device_m6312.c

@@ -68,15 +68,11 @@ static struct ppp_device_ops m6312_ops =
     .prepare = ppp_m6312_prepare,
 };
 
-/*
+/**
  * register m6312 into ppp_device
  *
- * @param
- *
- *
- *
- * @return  ppp_device function piont
- *
+ * @return  =0:   ppp_device register successfully
+ *          <0:   ppp_device register failed
  */
 int ppp_m6312_register(void)
 {

class/sim800/ppp_device_sim800.c

@@ -66,14 +66,11 @@ static struct ppp_device_ops sim800_ops =
     .prepare = ppp_sim800_prepare,
 };
 
-/*
+/**
  * register sim800 into ppp_device
  *
- * @param
- *
- *
- * @return  ppp_device function piont
- *
+ * @return  =0:   ppp_device register successfully
+ *          <0:   ppp_device register failed
  */
 int ppp_sim800_register(void)
 {

src/ppp_chat.c

@@ -21,13 +21,15 @@
 
 #define CHAT_READ_BUF_MAX 16
 
-// In order to match response, we need a string search algorithm
-// KMP and AC algorithm both are good choice, But we need the code
-// is simple, readable and use lower RAM/ROM.
-// So We use a simplified search algorithm, this alg is like the KMP.
-// Specifically we assume the failure vecotor is [-1, 0, 0, 0, ...]
-// This assuming is not work for all pattern string. Fortunately,
-// it's work  for this scene.
+/**
+* In order to match response, we need a string search algorithm
+* KMP and AC algorithm both are good choice, But we need the code
+* is simple, readable and use lower RAM/ROM.
+* So We use a simplified search algorithm, this alg is like the KMP.
+* Specifically we assume the failure vecotor is [-1, 0, 0, 0, ...]
+* This assuming is not work for all pattern string. Fortunately,
+* it's work  for this scene.
+*/
 
 #define DEFINE_MODEM_RESP_STRDATA_TABLE(id, str) [id] = str
 #define DEFINE_MODEM_RESP_STRLEN_TABLE(id, str)  [id] = (sizeof(str)-1)
@@ -74,14 +76,13 @@ static rt_bool_t resp_matched(rt_uint8_t resp_id, rt_uint8_t state)
     return state == resp_strlen[resp_id];
 }
 
-/*
- * chat_rx_ind , callback function if serial recieve data
- *
- * @param rt_device_t                       device
- *        rt_size_t                         size
+/**
+ * chat_rx_ind, callback function if serial recieve data
  *
- * @return  0   :   successful
+ * @param device the point of device driver structure, uart structure
+ * @param size  the indication callback function need this parameter
  *
+ * @return RT_EOK
  */
 static rt_err_t chat_rx_ind(rt_device_t device, rt_size_t size)
 {
@@ -89,14 +90,16 @@ static rt_err_t chat_rx_ind(rt_device_t device, rt_size_t size)
     return RT_EOK;
 }
 
-/*
- * chat_read_until , waitting for recieve data from serial
+/**
+ * chat_read_until, waitting for recieve data from serial
  *
- * @param struct rt_serial_device           *serial
- *        const struct modem_chat_data      *data
+ * @param serial    the point of device driver structure, uart structure
+ * @param buffer    the buffer is waitting for recieve uart data from ppp
+ * @param size      the max length of CHAT_READ_BUF_MAX
+ * @param stop      the max of tick time
  *
- * @return  0   :   timeout, can't recieve any data
- *          size:   the size of recieve data
+ * @return  >=0:   the length of read data
+ *          <0 :   rt_device_read failed
  */
 static rt_size_t chat_read_until(rt_device_t serial, void *buffer, rt_size_t size, rt_tick_t stop)
 {
@@ -116,13 +119,10 @@ static rt_size_t chat_read_until(rt_device_t serial, void *buffer, rt_size_t siz
     return rt_device_read(serial, 0, buffer, size);
 }
 
-/*
+/**
  * modem_flush_rx , clear data what is in the rx buffer
  *
- * @param struct rt_serial_device           *serial
- *
- * @return  RT_NULL: none
- *
+ * @param serial    the point of device driver structure, uart structure
  */
 static void modem_flush_rx(rt_device_t serial)
 {
@@ -131,14 +131,14 @@ static void modem_flush_rx(rt_device_t serial)
     while (rt_device_read(serial, 0, rdbuf, CHAT_READ_BUF_MAX));
 }
 
-/*
+/**
  * modem_chat_once , send an order to control modem
  *
- * @param struct rt_serial_device           *serial
- *        const struct modem_chat_data      *data
- *
- * @return  0: execute successful
+ * @param serial    the point of device driver structure, uart structure
+ * @param data      the AT command
  *
+ * @return  =0:   modem_chat_once successful
+ *          <0:   modem_chat_once failed
  */
 static rt_err_t modem_chat_once(rt_device_t serial, const struct modem_chat_data *data)
 {
@@ -184,15 +184,15 @@ static rt_err_t modem_chat_once(rt_device_t serial, const struct modem_chat_data
     return -RT_ETIMEOUT;
 }
 
-/*
- * modem_chat_internal , init modem and turn modem into ppp type
+/**
+ * modem_chat_internal , init modem or turn modem into ppp type
  *
- * @param struct rt_serial_device           *serial
- *        const struct modem_chat_data      *data
- *        rt_size_t                         len
- *
- * @return  0: execute successful
+ * @param serial    the point of device driver structure, uart structure
+ * @param data      the AT command, it is the address of chat strcuture, a collection of AT command
+ * @param len       the length of this collection of AT command
  *
+ * @return  =0:   modem_chat_internal successful
+ *          <0:   modem_chat_internal failed
  */
 static rt_err_t modem_chat_internal(rt_device_t serial, const struct modem_chat_data *data, rt_size_t len)
 {
@@ -220,15 +220,15 @@ static rt_err_t modem_chat_internal(rt_device_t serial, const struct modem_chat_
     return err;
 }
 
-/*
- * modem_chat , a function for ppp dailing to network
- *
- * @param struct ppp_device                 *device
- *        const struct modem_chat_data      *data
- *        rt_size_t                         len
+/**
+ * modem_chat , a function for ppp dailing to network, it will set rx_indicate
  *
- * @return  0: execute successful
+ * @param device    the point of device driver structure, uart structure
+ * @param data      the AT command, it is the address of chat strcuture, a collection of AT command
+ * @param len       the length of this collection of AT command
  *
+ * @return  =0:   modem_chat successful
+ *          <0:   modem_chat failed
  */
 rt_err_t modem_chat(rt_device_t serial, const struct modem_chat_data *data, rt_size_t len)
 {

src/ppp_device.c

@@ -47,14 +47,11 @@ enum
 
 static struct ppp_device *_g_ppp_device = RT_NULL;
 
-/*
+/**
  * dump ppp data according to hex format,you can see data what you recieve , send, and ppp_device dorp out
  *
- * @param const void *data
- *        size_t len
- *
- * @return  NULL
- *
+ * @param data      the data what you want to dump out
+ * @param len       the length of those data
  */
 #ifdef PPP_DEVICE_DEBUG
 static void ppp_debug_hexdump(const void *data, size_t len)
@@ -92,14 +89,13 @@ static void ppp_debug_hexdump(const void *data, size_t len)
 }
 #endif
 
-/*
- * Receive callback function , release rx_notice when uart acquire data
- *
- * @param rt_device_t
- *        rt_size_t
+/**
+ * Receive callback function , send PPP_EVENT_RX_NOTIFY event when uart acquire data
  *
- * @return  0: execute successful
+ * @param dev       the point of device driver structure, uart structure
+ * @param size      the indication callback function need this parameter
  *
+ * @return  RT_EOK
  */
 static rt_err_t ppp_device_rx_ind(rt_device_t dev, rt_size_t size)
 {
@@ -112,16 +108,15 @@ static rt_err_t ppp_device_rx_ind(rt_device_t dev, rt_size_t size)
     return RT_EOK;
 }
 
-/*
+/**
  *  using ppp_data_send send data to lwIP procotol stack     PPPoS serial output callback
  *
- * @param ppp_pcb   *pcb                 pcb PPP control block
- *        uint8_t   *data                data Buffer to write to serial port
- *        uint32_t  len                  len Length of the data buffer
- *        void      *ppp_device          ctx Context of callback , ppp_device
- *
- * @return  0: creat response fail
+ * @param pcb           pcb PPP control block
+ * @param data          data Buffer to write to serial port
+ * @param len           the Length of the data buffer
+ * @param ppp_device    ctx Context of callback , ppp_device
  *
+ * @return  the point of rt_device_write fucntion or RT_NULL
  */
 static uint32_t ppp_data_send(ppp_pcb *pcb, uint8_t *data, uint32_t len, void *ppp_device)
 {
@@ -141,15 +136,12 @@ static uint32_t ppp_data_send(ppp_pcb *pcb, uint8_t *data, uint32_t len, void *p
     return rt_device_write(device->uart, 0, data, len);
 }
 
-/*
+/**
  * ppp_status_changed callback function
  *
- * @param   ppp_pcb *pcb            protocol caontrol block
- *          int     err_code
- *          void    *ctx            reserver
- *
- * @return  0: creat response fail
- *
+ * @param pcb           protocol caontrol block
+ * @param err_code      the result of ppp conncet
+ * @param ctx           ctx Context of callback , ppp_device
  */
 static void ppp_status_changed(ppp_pcb *pcb, int err_code, void *ctx)
 {
@@ -206,13 +198,10 @@ static void ppp_status_changed(ppp_pcb *pcb, int err_code, void *ctx)
         rt_event_send(&pppdev->event, PPP_EVENT_LOST);
 }
 
-/*
+/**
  * prepare for starting recieve ppp frame, clear recieve buff and set ppp device state
  *
- * @param   struct ppp_device *device
- *
- * @return  NULL
- *
+ * @param device  the point of device driver structure, ppp_device structure
  */
 static inline void ppp_start_receive_frame(struct ppp_device *device)
 {
@@ -221,12 +210,10 @@ static inline void ppp_start_receive_frame(struct ppp_device *device)
 }
 
 #ifdef PPP_DEVICE_DEBUG_DROP
-/*
+/**
  * ppp_show_dropbuf, printf the data whom ppp devcie drop out, and increase drop data conut
  *
- * @param   struct ppp_device *device
- *
- * @return  NULL
+ * @param device  the point of device driver structure, ppp_device structure
  */
 static inline void ppp_show_dropbuf(struct ppp_device *device)
 {
@@ -238,13 +225,10 @@ static inline void ppp_show_dropbuf(struct ppp_device *device)
     device->droppos = 0;
 }
 
-/*
+/**
  * ppp_show_rxbuf_as_drop, printf the data whom ppp devcie drop out, and increase drop data conut
  *
- * @param   struct ppp_device *device
- *
- * @return  NULL
- *
+ * @param device  the point of device driver structure, ppp_device structure
  */
 static inline void ppp_show_rxbuf_as_drop(struct ppp_device *device)
 {
@@ -256,13 +240,10 @@ static inline void ppp_show_rxbuf_as_drop(struct ppp_device *device)
     device->rxpos = 0;
 }
 
-/*
+/**
  * ppp_rxbuf_drop, printf the data whom ppp devcie drop out
  *
- * @param   struct ppp_device *device
- *
- * @return  NULL
- *
+ * @param device  the point of device driver structure, ppp_device structure
  */
 static inline void ppp_rxbuf_drop(struct ppp_device *device)
 {
@@ -297,13 +278,10 @@ static inline void ppp_show_dropbuf(struct ppp_device *device) {}
 #define ppp_rxbuf_drop(device) ppp_start_receive_frame(device)
 #endif /* PPP_DEVICE_DEBUG_DROP */
 
-/*
+/**
  * ppp_processdata_enter, prepare to recieve data
  *
- * @param   struct ppp_device *device
- *
- * @return  NULL
- *
+ * @param device  the point of device driver structure, ppp_device structure
  */
 static inline void ppp_processdata_enter(struct ppp_device *device)
 {
@@ -313,13 +291,10 @@ static inline void ppp_processdata_enter(struct ppp_device *device)
 #endif
 }
 
-/*
+/**
  * ppp_processdata_leave, throw ppp device data when ppp connection is closed
  *
- * @param   struct ppp_device *device
- *
- * @return  NULL
- *
+ * @param device  the point of device driver structure, ppp_device structure
  */
 static inline void ppp_processdata_leave(struct ppp_device *device)
 {
@@ -327,14 +302,11 @@ static inline void ppp_processdata_leave(struct ppp_device *device)
     ppp_show_dropbuf(device);
 }
 
-/*
+/**
  * ppp_savebyte, save this data into ppp device buff
  *
- * @param   struct ppp_device   *device
- *          rt_uint8_t          dat
- *
- * @return  NULL
- *
+ * @param   device  the point of device driver structure, ppp_device structure
+ * @param   dat     the character of recieve data
  */
 static inline void ppp_savebyte(struct ppp_device *device, rt_uint8_t dat)
 {
@@ -342,15 +314,12 @@ static inline void ppp_savebyte(struct ppp_device *device, rt_uint8_t dat)
     device->rxbuf[device->rxpos++] = dat;
 }
 
-/*
+/**
  * ppp_recv_processdata, save data from uart, recieve complete ppp frame data
  *
- * @param   struct ppp_device       *device
- *          const rt_uint8_t        *buf
- *          rt_size_t               len
- *
- * @return  NULL
- *
+ * @param   device  the point of device driver structure, ppp_device structure
+ * @param   buf     the address of recieve data from uart
+ * @param   len     the length of recieve data
  */
 static void ppp_recv_processdata(struct ppp_device *device, const rt_uint8_t *buf, rt_size_t len)
 {
@@ -407,14 +376,12 @@ process_dat:
     }
 }
 
-/*
+/**
  * Receive thread , store uart data and transform tcpip stack
  *
- * @param ppp_device *device
- *
- *
- * @return  0: execute successful
+ * @param device    the point of device driver structure, ppp_device structure
  *
+ * @return  RT_EOK  we shouldn't let the recieve thread return data, recieve thread need keepalive all the time
  */
 static int ppp_recv_entry(struct ppp_device *device)
 {
@@ -480,14 +447,14 @@ static int ppp_recv_entry(struct ppp_device *device)
     return RT_EOK;
 }
 
-/*
+/**
  * Creat a thread to creat receive thread function
  *
- * @param ppp_device *device
- *
- *
- * @return  0: execute successful
+ * @param   device      the point of device driver structure, ppp_device structure
  *
+ * @return  RT_EOK      recieve thread create and startup successfully
+ *          -RT_ERROR   create recieve thread successfully
+ *          -RT_ENOMEM  startup recieve thread successfully
  */
 static int ppp_recv_entry_creat(struct ppp_device *device)
 {
@@ -522,11 +489,9 @@ __exit:
 /**
  * ppp device init function,set ops funciton and base config
  *
- * @param dev the pointer of device driver structure
- *
- *
- * @return  0: execute successful
+ * @param device    the point of device driver structure, rt_device structure
  *
+ * @return  RT_EOK
  */
 static rt_err_t ppp_device_init(struct rt_device *device)
 {
@@ -542,14 +507,13 @@ static rt_err_t ppp_device_init(struct rt_device *device)
     return RT_EOK;
 }
 
-/*
+/**
  * initialize ppp device and set callback function
  *
- * @param rt_device_t *device
- *        rt_uint16_t oflag
- *
- * @return  0:  execute successful
+ * @param device    the point of device driver structure, rt_device structure
+ * @param oflag     the open flag of rt_device
  *
+ * @return  the result
  */
 static rt_err_t ppp_device_open(struct rt_device *device, rt_uint16_t oflag)
 {
@@ -642,13 +606,12 @@ __exit:
     return result;
 }
 
-/*
+/**
  * Close ppp device
  *
- * @param rt_device_t   *device
- *
+ * @param device    the point of device driver structure, rt_device structure
  *
- * @return  0: execute successful
+ * @return  RT_EOK
  */
 static rt_err_t ppp_device_close(struct rt_device *device)
 {
@@ -674,14 +637,14 @@ static rt_err_t ppp_device_close(struct rt_device *device)
     return RT_EOK;
 }
 
-/*
- * Control ppp device , access ppp mode or accsee AT mode
+/**
+ * Control ppp device , access ppp mode or accsee AT mode; but not it is useless
  *
- * @param rt_device_t   *device
- *        int           cmd
- *        void          *args
+ * @param device    the point of device driver structure, rt_device structure
+ * @param cmd       the command of device
+ * @param args      the private data of you send
  *
- * @return  0: execute successful
+ * @return  -RT_ENOSYS
  */
 static rt_err_t ppp_device_control(struct rt_device *device,int cmd, void *args)
 {
@@ -690,10 +653,7 @@ static rt_err_t ppp_device_control(struct rt_device *device,int cmd, void *args)
     return -RT_ENOSYS;
 }
 
-/*
- * ppp device ops
- *
- */
+/* ppp device ops */
 #ifdef RT_USING_DEVICE_OPS
 const struct rt_device_ops ppp_device_ops =
 {
@@ -704,13 +664,15 @@ const struct rt_device_ops ppp_device_ops =
 };
 #endif
 
-/*
+/**
  * Register ppp_device into rt_device frame,set ops function to rt_device inferface
  *
- * @param struct ppp_device *ppp_device
- *
- * @return  0: execute successful
+ * @param ppp_device    the point of device driver structure, ppp_device structure
+ * @param dev_name      the name of ppp_device name
+ * @param uart_name     the name of uart name what you used
+ * @param user_data     private data
  *
+ * @return  RT_EOK      ppp_device registered into rt_device frame successfully
  */
 int ppp_device_register(struct ppp_device *ppp_device, const char *dev_name, const char *uart_name, void *user_data)
 {
@@ -753,15 +715,15 @@ int ppp_device_register(struct ppp_device *ppp_device, const char *dev_name, con
     return result;
 }
 
-/*
+/**
  * attach data interface device into ppp device frame
  *
- * @param       struct ppp_device *ppp_device
- *              char *uart_name
- *              void *user_data
- * @return  0: execute successful
- *         -1: error
+ * @param   ppp_device      the point of device driver structure, ppp_device structure
+ * @param   uart_name       the name of uart name what you used
+ * @param   user_data       private data
  *
+ * @return  RT_EOK          execute successful
+ * @return -RT_ERROR        error
  */
 int ppp_device_attach(struct ppp_device *ppp_device, const char *uart_name, void *user_data)
 {
@@ -784,14 +746,13 @@ int ppp_device_attach(struct ppp_device *ppp_device, const char *uart_name, void
     return RT_EOK;
 }
 
-/*
+/**
  * detach data interface device from ppp device frame
  *
- * @param       struct ppp_device *ppp_device
- *
- * @return  0: execute successful
- *         -1: error
+ * @param   ppp_device      the point of device driver structure, ppp_device structure
  *
+ * @return  RT_EOK          execute successful
+ * @return -RT_ERROR        error
  */
 int ppp_device_detach(struct ppp_device *ppp_device)
 {

src/ppp_netif.c

@@ -20,6 +20,14 @@
 
 extern const struct netdev_ops lwip_netdev_ops;
 
+/**
+ * add ppp_netdev into netdev
+ *
+ * @param ppp_netif      the piont of netif control block
+ *
+ * @return  RT_EOK       execute successful
+ * @return  -ERR_IF      netif error, can't alloc memory for netdev
+ */
 rt_err_t ppp_netdev_add(struct netif *ppp_netif)
 {
 #define LWIP_NETIF_NAME_LEN 2
@@ -67,6 +75,13 @@ rt_err_t ppp_netdev_add(struct netif *ppp_netif)
     return result;
 }
 
+/**
+ * refresh ppp_netif state, include DNS and netdev flag information
+ *
+ * @param ppp_netif      the piont of netif control block
+ *
+ * @return  RT_EOK       execute successful
+ */
 rt_err_t ppp_netdev_refresh(struct netif *ppp_netif)
 {
     extern const ip_addr_t *dns_getserver(u8_t numdns);
@@ -98,6 +113,11 @@ rt_err_t ppp_netdev_refresh(struct netif *ppp_netif)
     return RT_EOK;
 }
 
+/**
+ * delete netdev of ppp_netif create
+ *
+ * @param ppp_netif      the piont of netif control block
+ */
 void ppp_netdev_del(struct netif *ppp_netif)
 {
     char name[LWIP_NETIF_NAME_LEN + 1];