[kservice] 完善 API 注释

1 files changed, 146 insertions, 80 deletions

diff --git a/src/kservice.c b/src/kservice.c
index 91872492fb..25d34dfc47 100644
--- a/src/kservice.c
+++ b/src/kservice.c
@@ -43,8 +43,8 @@ static volatile int __rt_errno;
 static rt_device_t _console_device = RT_NULL;
 #endif
 
-/*
- * This function will get errno
+/**
+ * This function gets the global errno for the current thread.
  *
  * @return errno
  */
@@ -66,10 +66,10 @@ rt_err_t rt_get_errno(void)
 }
 RTM_EXPORT(rt_get_errno);
 
-/*
- * This function will set errno
+/**
+ * This function sets the global errno for the current thread.
  *
- * @param error the errno shall be set
+ * @param error is the errno shall be set.
  */
 void rt_set_errno(rt_err_t error)
 {
@@ -96,9 +96,9 @@ void rt_set_errno(rt_err_t error)
 RTM_EXPORT(rt_set_errno);
 
 /**
- * This function returns errno.
+ * This function returns the address of the current thread errno.
  *
- * @return the errno in the system
+ * @return The errno address.
  */
 int *_rt_errno(void)
 {
@@ -116,13 +116,16 @@ int *_rt_errno(void)
 RTM_EXPORT(_rt_errno);
 
 /**
- * This function will set the content of memory to specified value
+ * This function will set the content of memory to specified value.
+ *
+ * @param  s is the address of source memory, point to the memory block to be filled.
+ *
+ * @param  c is the value to be set. The value is passed in int form, but the function
+ *         uses the unsigned character form of the value when filling the memory block.
  *
- * @param s the address of source memory
- * @param c the value shall be set in content
- * @param count the copied length
+ * @param  count number of bytes to be set.
  *
- * @return the address of source memory
+ * @return The address of source memory.
  */
 RT_WEAK void *rt_memset(void *s, int c, rt_ubase_t count)
 {
@@ -200,14 +203,15 @@ RTM_EXPORT(rt_memset);
 
 #ifndef RT_USING_ASM_MEMCPY
 /**
- * This function will copy memory content from source address to destination
- * address.
+ * This function will copy memory content from source address to destination address.
  *
- * @param dst the address of destination memory
- * @param src  the address of source memory
- * @param count the copied length
+ * @param  dst is the address of destination memory, points to the copied content.
  *
- * @return the address of destination memory
+ * @param  src  is the address of source memory, pointing to the data source to be copied.
+ *
+ * @param  count is the copied length.
+ *
+ * @return The address of destination memory
  */
 void *rt_memcpy(void *dst, const void *src, rt_ubase_t count)
 {
@@ -287,13 +291,16 @@ RTM_EXPORT(rt_memcpy);
 
 /**
  * This function will move memory content from source address to destination
- * address.
+ * address. If the destination memory does not overlap with the source memory,
+ * the function is the same as memcpy().
+ *
+ * @param  dst is the address of destination memory, points to the copied content.
  *
- * @param dest the address of destination memory
- * @param src  the address of source memory
- * @param n the copied length
+ * @param  src is the address of source memory, point to the data source to be copied.
  *
- * @return the address of destination memory
+ * @param  count is the copied length.
+ *
+ * @return The address of destination memory.
  */
 void *rt_memmove(void *dest, const void *src, rt_ubase_t n)
 {
@@ -318,13 +325,18 @@ void *rt_memmove(void *dest, const void *src, rt_ubase_t n)
 RTM_EXPORT(rt_memmove);
 
 /**
- * This function will compare two areas of memory
+ * This function will compare two areas of memory.
+ *
+ * @param  cs is a block of memory.
+ *
+ * @param  ct is another block of memory.
  *
- * @param cs one area of memory
- * @param ct another area of memory
- * @param count the size of the area
+ * @param  count is the size of the area.
  *
- * @return the result
+ * @return Compare the results:
+ *         If the result < 0, cs is smaller than ct.
+ *         If the result > 0, cs is greater than ct.
+ *         If the result = 0, cs is equal to ct.
  */
 RT_WEAK rt_int32_t rt_memcmp(const void *cs, const void *ct, rt_ubase_t count)
 {
@@ -340,12 +352,14 @@ RT_WEAK rt_int32_t rt_memcmp(const void *cs, const void *ct, rt_ubase_t count)
 RTM_EXPORT(rt_memcmp);
 
 /**
- * This function will return the first occurrence of a string.
+ * This function will return the first occurrence of a string, without the
+ * terminator '\0'.
  *
- * @param s1 the source string
- * @param s2 the find string
+ * @param  s1 is the source string.
  *
- * @return the first occurrence of a s2 in s1, or RT_NULL if no found.
+ * @param  s2 is the find string.
+ *
+ * @return The first occurrence of a s2 in s1, or RT_NULL if no found.
  */
 char *rt_strstr(const char *s1, const char *s2)
 {
@@ -370,10 +384,14 @@ RTM_EXPORT(rt_strstr);
 /**
  * This function will compare two strings while ignoring differences in case
  *
- * @param a the string to be compared
- * @param b the string to be compared
+ * @param  a is the string to be compared.
+ *
+ * @param  b is the string to be compared.
  *
- * @return the result
+ * @return Compare the results:
+ *         If the result < 0, a is smaller than a.
+ *         If the result > 0, a is greater than a.
+ *         If the result = 0, a is equal to a.
  */
 rt_int32_t rt_strcasecmp(const char *a, const char *b)
 {
@@ -397,11 +415,13 @@ RTM_EXPORT(rt_strcasecmp);
 /**
  * This function will copy string no more than n bytes.
  *
- * @param dst the string to copy
- * @param src the string to be copied
- * @param n the maximum copied length
+ * @param  dst points to the address used to store the copied content.
+ *
+ * @param  src is the string to be copied.
  *
- * @return the result
+ * @param  n is the maximum copied length.
+ *
+ * @return The address where the copied content is stored.
  */
 char *rt_strncpy(char *dst, const char *src, rt_ubase_t n)
 {
@@ -427,13 +447,18 @@ char *rt_strncpy(char *dst, const char *src, rt_ubase_t n)
 RTM_EXPORT(rt_strncpy);
 
 /**
- * This function will compare two strings with specified maximum length
+ * This function will compare two strings with specified maximum length.
+ *
+ * @param  cs is the string to be compared.
+ *
+ * @param  ct is the string to be compared.
  *
- * @param cs the string to be compared
- * @param ct the string to be compared
- * @param count the maximum compare length
+ * @param  count is the maximum compare length.
  *
- * @return the result
+ * @return Compare the results:
+ *         If the result < 0, cs is smaller than ct.
+ *         If the result > 0, cs is greater than ct.
+ *         If the result = 0, cs is equal to ct.
  */
 rt_int32_t rt_strncmp(const char *cs, const char *ct, rt_ubase_t count)
 {
@@ -451,12 +476,16 @@ rt_int32_t rt_strncmp(const char *cs, const char *ct, rt_ubase_t count)
 RTM_EXPORT(rt_strncmp);
 
 /**
- * This function will compare two strings without specified length
+ * This function will compare two strings without specified length.
  *
- * @param cs the string to be compared
- * @param ct the string to be compared
+ * @param  cs is the string to be compared.
  *
- * @return the result
+ * @param  ct is the string to be compared.
+ *
+ * @return Compare the results:
+ *         If the result < 0, cs is smaller than ct.
+ *         If the result > 0, cs is greater than ct.
+ *         If the result = 0, cs is equal to ct.
  */
 rt_int32_t rt_strcmp(const char *cs, const char *ct)
 {
@@ -477,9 +506,11 @@ RTM_EXPORT(rt_strcmp);
  * first maxlen characters in the string pointed to by s and never
  * beyond s+maxlen.
  *
- * @param s the string
- * @param maxlen the max size
- * @return the length of string
+ * @param  s is the string.
+ *
+ * @param  maxlen is the max size.
+ *
+ * @return The length of string.
  */
 rt_size_t rt_strnlen(const char *s, rt_ubase_t maxlen)
 {
@@ -496,9 +527,9 @@ RTM_EXPORT(rt_strnlen);
  * This function will return the length of a string, which terminate will
  * null character.
  *
- * @param s the string
+ * @param  s is the string
  *
- * @return the length of string
+ * @return The length of string.
  */
 rt_size_t rt_strlen(const char *s)
 {
@@ -517,9 +548,9 @@ RTM_EXPORT(rt_strlen);
 /**
  * This function will duplicate a string.
  *
- * @param s the string to be duplicated
+ * @param  s is the string to be duplicated.
  *
- * @return the duplicated string pointer
+ * @return The string address of the copy.
  */
 char *rt_strdup(const char *s)
 {
@@ -556,6 +587,13 @@ RTM_EXPORT(rt_show_version);
 #define _ISDIGIT(c)  ((unsigned)((c) - '0') < 10)
 
 #ifdef RT_PRINTF_LONGLONG
+/**
+ * This function will duplicate a string.
+ *
+ * @param  s the string to be duplicated
+ *
+ * @return the duplicated string pointer
+ */
 rt_inline int divide(long long *n, int base)
 {
     int res;
@@ -784,6 +822,19 @@ static char *print_number(char *buf,
     return buf;
 }
 
+/**
+ * This function will fill a formatted string to buffer.
+ *
+ * @param  buf is the buffer to save formatted string.
+ *
+ * @param  size is the size of buffer.
+ *
+ * @param  fmt is the format parameters.
+ *
+ * @param  args is a list of variable parameters.
+ *
+ * @return The number of characters actually written to buffer.
+ */
 rt_int32_t rt_vsnprintf(char       *buf,
                         rt_size_t   size,
                         const char *fmt,
@@ -1051,11 +1102,15 @@ rt_int32_t rt_vsnprintf(char       *buf,
 RTM_EXPORT(rt_vsnprintf);
 
 /**
- * This function will fill a formatted string to buffer
+ * This function will fill a formatted string to buffer.
  *
- * @param buf the buffer to save formatted string
- * @param size the size of buffer
- * @param fmt the format
+ * @param  buf is the buffer to save formatted string.
+ *
+ * @param  size is the size of buffer.
+ *
+ * @param  fmt is the format parameters.
+ *
+ * @return The number of characters actually written to buffer.
  */
 rt_int32_t rt_snprintf(char *buf, rt_size_t size, const char *fmt, ...)
 {
@@ -1071,11 +1126,15 @@ rt_int32_t rt_snprintf(char *buf, rt_size_t size, const char *fmt, ...)
 RTM_EXPORT(rt_snprintf);
 
 /**
- * This function will fill a formatted string to buffer
+ * This function will fill a formatted string to buffer.
+ *
+ * @param  buf is the buffer to save formatted string.
+ *
+ * @param  format is the format parameters.
  *
- * @param buf the buffer to save formatted string
- * @param arg_ptr the arg_ptr
- * @param format the format
+ * @param  arg_ptr is a list of variable parameters.
+ *
+ * @return The number of characters actually written to buffer.
  */
 rt_int32_t rt_vsprintf(char *buf, const char *format, va_list arg_ptr)
 {
@@ -1086,8 +1145,11 @@ RTM_EXPORT(rt_vsprintf);
 /**
  * This function will fill a formatted string to buffer
  *
- * @param buf the buffer to save formatted string
- * @param format the format
+ * @param  buf the buffer to save formatted string.
+ *
+ * @param  format is the format parameters.
+ *
+ * @return The number of characters actually written to buffer.
  */
 rt_int32_t rt_sprintf(char *buf, const char *format, ...)
 {
@@ -1108,7 +1170,7 @@ RTM_EXPORT(rt_sprintf);
 /**
  * This function returns the device using in console.
  *
- * @return the device using in console or RT_NULL
+ * @return Returns the console device pointer or RT_NULL.
  */
 rt_device_t rt_console_get_device(void)
 {
@@ -1121,7 +1183,7 @@ RTM_EXPORT(rt_console_get_device);
  * After set a device to console, all output of rt_kprintf will be
  * redirected to this new device.
  *
- * @param name the name of new console device
+ * @param  name is the name of new console device.
  *
  * @return the old console device handler on successful, or RT_NULL on failure.
  */
@@ -1165,7 +1227,7 @@ RTM_EXPORT(rt_hw_console_output);
 /**
  * This function will put string to the console.
  *
- * @param str the string output to the console.
+ * @param str is the string output to the console.
  */
 void rt_kputs(const char *str)
 {
@@ -1186,9 +1248,9 @@ void rt_kputs(const char *str)
 }
 
 /**
- * This function will print a formatted string on system console
+ * This function will print a formatted string on system console.
  *
- * @param fmt the format
+ * @param fmt is the format parameters.
  */
 RT_WEAK void rt_kprintf(const char *fmt, ...)
 {
@@ -1227,10 +1289,12 @@ RTM_EXPORT(rt_kprintf);
  * This function allocates a memory block, which address is aligned to the
  * specified alignment size.
  *
- * @param size the allocated memory block size
- * @param align the alignment size
+ * @param  size is the allocated memory block size.
  *
- * @return the allocated memory block on successful, otherwise returns RT_NULL
+ * @param  align is the alignment size.
+ *
+ * @return The memory block address was returned successfully, otherwise it was
+ *         returned empty RT_NULL.
  */
 RT_WEAK void *rt_malloc_align(rt_size_t size, rt_size_t align)
 {
@@ -1276,7 +1340,7 @@ RTM_EXPORT(rt_malloc_align);
  * This function release the memory block, which is allocated by
  * rt_malloc_align function and address is aligned.
  *
- * @param ptr the memory block pointer
+ * @param ptr is the memory block pointer.
  */
 RT_WEAK void rt_free_align(void *ptr)
 {
@@ -1316,8 +1380,8 @@ const rt_uint8_t __lowest_bit_bitmap[] =
  * Bits are numbered starting at 1 (the least significant bit).  A return value of
  * zero from any of these functions means that the argument was zero.
  *
- * @return return the index of the first bit set. If value is 0, then this function
- * shall return 0.
+ * @return Return the index of the first bit set. If value is 0, then this function
+ *         shall return 0.
  */
 int __rt_ffs(int value)
 {
@@ -1344,7 +1408,7 @@ void (*rt_assert_hook)(const char *ex, const char *func, rt_size_t line);
 /**
  * This function will set a hook function to RT_ASSERT(EX). It will run when the expression is false.
  *
- * @param hook the hook function
+ * @param hook is the hook function.
  */
 void rt_assert_set_hook(void (*hook)(const char *ex, const char *func, rt_size_t line))
 {
@@ -1354,9 +1418,11 @@ void rt_assert_set_hook(void (*hook)(const char *ex, const char *func, rt_size_t
 /**
  * The RT_ASSERT function.
  *
- * @param ex the assertion condition string
- * @param func the function name when assertion.
- * @param line the file line number when assertion.
+ * @param ex is the assertion condition string.
+ *
+ * @param func is the function name when assertion.
+ *
+ * @param line is the file line number when assertion.
  */
 void rt_assert_handler(const char *ex_string, const char *func, rt_size_t line)
 {