modify annotation for sys_arch_mbox_tryfetch

4 files changed, 44 insertions, 8 deletions

diff --git a/components/net/lwip-1.4.1/src/arch/sys_arch.c b/components/net/lwip-1.4.1/src/arch/sys_arch.c
index 09de3f3ecc..3cdb637d15 100644
--- a/components/net/lwip-1.4.1/src/arch/sys_arch.c
+++ b/components/net/lwip-1.4.1/src/arch/sys_arch.c
@@ -515,10 +515,19 @@ u32_t sys_arch_mbox_fetch(sys_mbox_t *mbox, void **msg, u32_t timeout)
     return tick;
 }
 
-/** Wait for a new message to arrive in the mbox
+/**
+ * @ingroup sys_mbox
+ * This is similar to sys_arch_mbox_fetch, however if a message is not
+ * present in the mailbox, it immediately returns with the code
+ * SYS_MBOX_EMPTY. On success 0 is returned.
+ * To allow for efficient implementations, this can be defined as a
+ * function-like macro in sys_arch.h instead of a normal function. For
+ * example, a naive implementation could be:
+ * \#define sys_arch_mbox_tryfetch(mbox,msg) sys_arch_mbox_fetch(mbox,msg,1)
+ * although this would introduce unnecessary delays.
+ *
  * @param mbox mbox to get a message from
  * @param msg pointer where the message is stored
- * @param timeout maximum time (in milliseconds) to wait for a message
  * @return 0 (milliseconds) if a message has been received
  *         or SYS_MBOX_EMPTY if the mailbox is empty
  */
diff --git a/components/net/lwip-2.0.2/src/arch/sys_arch.c b/components/net/lwip-2.0.2/src/arch/sys_arch.c
index 6556fd0c9f..b779264f96 100644
--- a/components/net/lwip-2.0.2/src/arch/sys_arch.c
+++ b/components/net/lwip-2.0.2/src/arch/sys_arch.c
@@ -526,10 +526,19 @@ u32_t sys_arch_mbox_fetch(sys_mbox_t *mbox, void **msg, u32_t timeout)
     return tick;
 }
 
-/** Wait for a new message to arrive in the mbox
+/**
+ * @ingroup sys_mbox
+ * This is similar to sys_arch_mbox_fetch, however if a message is not
+ * present in the mailbox, it immediately returns with the code
+ * SYS_MBOX_EMPTY. On success 0 is returned.
+ * To allow for efficient implementations, this can be defined as a
+ * function-like macro in sys_arch.h instead of a normal function. For
+ * example, a naive implementation could be:
+ * \#define sys_arch_mbox_tryfetch(mbox,msg) sys_arch_mbox_fetch(mbox,msg,1)
+ * although this would introduce unnecessary delays.
+ *
  * @param mbox mbox to get a message from
  * @param msg pointer where the message is stored
- * @param timeout maximum time (in milliseconds) to wait for a message
  * @return 0 (milliseconds) if a message has been received
  *         or SYS_MBOX_EMPTY if the mailbox is empty
  */
diff --git a/components/net/lwip-2.0.3/src/arch/sys_arch.c b/components/net/lwip-2.0.3/src/arch/sys_arch.c
index 6556fd0c9f..b779264f96 100644
--- a/components/net/lwip-2.0.3/src/arch/sys_arch.c
+++ b/components/net/lwip-2.0.3/src/arch/sys_arch.c
@@ -526,10 +526,19 @@ u32_t sys_arch_mbox_fetch(sys_mbox_t *mbox, void **msg, u32_t timeout)
     return tick;
 }
 
-/** Wait for a new message to arrive in the mbox
+/**
+ * @ingroup sys_mbox
+ * This is similar to sys_arch_mbox_fetch, however if a message is not
+ * present in the mailbox, it immediately returns with the code
+ * SYS_MBOX_EMPTY. On success 0 is returned.
+ * To allow for efficient implementations, this can be defined as a
+ * function-like macro in sys_arch.h instead of a normal function. For
+ * example, a naive implementation could be:
+ * \#define sys_arch_mbox_tryfetch(mbox,msg) sys_arch_mbox_fetch(mbox,msg,1)
+ * although this would introduce unnecessary delays.
+ *
  * @param mbox mbox to get a message from
  * @param msg pointer where the message is stored
- * @param timeout maximum time (in milliseconds) to wait for a message
  * @return 0 (milliseconds) if a message has been received
  *         or SYS_MBOX_EMPTY if the mailbox is empty
  */
diff --git a/components/net/lwip-2.1.2/src/arch/sys_arch.c b/components/net/lwip-2.1.2/src/arch/sys_arch.c
index c89ab737c9..62dc493007 100644
--- a/components/net/lwip-2.1.2/src/arch/sys_arch.c
+++ b/components/net/lwip-2.1.2/src/arch/sys_arch.c
@@ -540,10 +540,19 @@ u32_t sys_arch_mbox_fetch(sys_mbox_t *mbox, void **msg, u32_t timeout)
     return tick;
 }
 
-/** Wait for a new message to arrive in the mbox
+/**
+ * @ingroup sys_mbox
+ * This is similar to sys_arch_mbox_fetch, however if a message is not
+ * present in the mailbox, it immediately returns with the code
+ * SYS_MBOX_EMPTY. On success 0 is returned.
+ * To allow for efficient implementations, this can be defined as a
+ * function-like macro in sys_arch.h instead of a normal function. For
+ * example, a naive implementation could be:
+ * \#define sys_arch_mbox_tryfetch(mbox,msg) sys_arch_mbox_fetch(mbox,msg,1)
+ * although this would introduce unnecessary delays.
+ *
  * @param mbox mbox to get a message from
  * @param msg pointer where the message is stored
- * @param timeout maximum time (in milliseconds) to wait for a message
  * @return 0 (milliseconds) if a message has been received
  *         or SYS_MBOX_EMPTY if the mailbox is empty
  */