Merge pull request #5040 from yangjie11/comments

[kernel]Normalized kernel API annotation

1 files changed, 69 insertions, 61 deletions

diff --git a/src/object.c b/src/object.c
index 718b0aa5b2..66d5775bd7 100644
--- a/src/object.c
+++ b/src/object.c
@@ -120,10 +120,10 @@ void (*rt_object_put_hook)(struct rt_object *object);
 /**@{*/
 
 /**
- * This function will set a hook function, which will be invoked when object
- * attaches to kernel object system.
+ * @brief This function will set a hook function, which will be invoked when object
+ *        attaches to kernel object system.
  *
- * @param hook the hook function
+ * @param hook is the hook function.
  */
 void rt_object_attach_sethook(void (*hook)(struct rt_object *object))
 {
@@ -131,10 +131,10 @@ void rt_object_attach_sethook(void (*hook)(struct rt_object *object))
 }
 
 /**
- * This function will set a hook function, which will be invoked when object
- * detaches from kernel object system.
+ * @brief This function will set a hook function, which will be invoked when object
+ *        detaches from kernel object system.
  *
- * @param hook the hook function
+ * @param hook is the hook function
  */
 void rt_object_detach_sethook(void (*hook)(struct rt_object *object))
 {
@@ -142,17 +142,17 @@ void rt_object_detach_sethook(void (*hook)(struct rt_object *object))
 }
 
 /**
- * This function will set a hook function, which will be invoked when object
- * is taken from kernel object system.
+ * @brief This function will set a hook function, which will be invoked when object
+ *        is taken from kernel object system.
  *
- * The object is taken means:
- * semaphore - semaphore is taken by thread
- * mutex - mutex is taken by thread
- * event - event is received by thread
- * mailbox - mail is received by thread
- * message queue - message is received by thread
+ *        The object is taken means:
+ *            semaphore - semaphore is taken by thread
+ *            mutex - mutex is taken by thread
+ *            event - event is received by thread
+ *            mailbox - mail is received by thread
+ *            message queue - message is received by thread
  *
- * @param hook the hook function
+ * @param hook is the hook function.
  */
 void rt_object_trytake_sethook(void (*hook)(struct rt_object *object))
 {
@@ -160,18 +160,18 @@ void rt_object_trytake_sethook(void (*hook)(struct rt_object *object))
 }
 
 /**
- * This function will set a hook function, which will be invoked when object
- * have been taken from kernel object system.
+ * @brief This function will set a hook function, which will be invoked when object
+ *        have been taken from kernel object system.
  *
- * The object have been taken means:
- * semaphore - semaphore have been taken by thread
- * mutex - mutex have been taken by thread
- * event - event have been received by thread
- * mailbox - mail have been received by thread
- * message queue - message have been received by thread
- * timer - timer is started
+ *        The object have been taken means:
+ *            semaphore - semaphore have been taken by thread
+ *            mutex - mutex have been taken by thread
+ *            event - event have been received by thread
+ *            mailbox - mail have been received by thread
+ *            message queue - message have been received by thread
+ *            timer - timer is started
  *
- * @param hook the hook function
+ * @param hook the hook function.
  */
 void rt_object_take_sethook(void (*hook)(struct rt_object *object))
 {
@@ -179,10 +179,10 @@ void rt_object_take_sethook(void (*hook)(struct rt_object *object))
 }
 
 /**
- * This function will set a hook function, which will be invoked when object
- * is put to kernel object system.
+ * @brief This function will set a hook function, which will be invoked when object
+ *        is put to kernel object system.
  *
- * @param hook the hook function
+ * @param hook is the hook function
  */
 void rt_object_put_sethook(void (*hook)(struct rt_object *object))
 {
@@ -199,9 +199,9 @@ void rt_object_put_sethook(void (*hook)(struct rt_object *object))
 /**@{*/
 
 /**
- * This function will return the specified type of object information.
+ * @brief This function will return the specified type of object information.
  *
- * @param type the type of object, which can be
+ * @param type is the type of object, which can be
  *             RT_Object_Class_Thread/Semaphore/Mutex... etc
  *
  * @return the object type information or RT_NULL
@@ -219,10 +219,11 @@ rt_object_get_information(enum rt_object_class_type type)
 RTM_EXPORT(rt_object_get_information);
 
 /**
- * This function will return the length of object list in object container.
+ * @brief This function will return the length of object list in object container.
  *
- * @param type the type of object, which can be
+ * @param type is the type of object, which can be
  *             RT_Object_Class_Thread/Semaphore/Mutex... etc
+ *
  * @return the length of object list
  */
 int rt_object_get_length(enum rt_object_class_type type)
@@ -248,15 +249,17 @@ int rt_object_get_length(enum rt_object_class_type type)
 RTM_EXPORT(rt_object_get_length);
 
 /**
- * This function will copy the object pointer of the specified type,
- * with the maximum size specified by maxlen.
+ * @brief This function will copy the object pointer of the specified type,
+ *        with the maximum size specified by maxlen.
  *
- * @param type the type of object, which can be
+ * @param type is the type of object, which can be
  *             RT_Object_Class_Thread/Semaphore/Mutex... etc
- * @param pointers the pointers will be saved to
- * @param maxlen the maximum number of pointers can be saved
  *
- * @return the copied number of object pointers
+ * @param pointers is the pointer will be saved to.
+ *
+ * @param maxlen is the maximum number of pointers can be saved.
+ *
+ * @return the copied number of object pointers.
  */
 int rt_object_get_pointers(enum rt_object_class_type type, rt_object_t *pointers, int maxlen)
 {
@@ -290,12 +293,14 @@ int rt_object_get_pointers(enum rt_object_class_type type, rt_object_t *pointers
 RTM_EXPORT(rt_object_get_pointers);
 
 /**
- * This function will initialize an object and add it to object system
- * management.
+ * @brief This function will initialize an object and add it to object system
+ *        management.
+ *
+ * @param object is the specified object to be initialized.
  *
- * @param object the specified object to be initialized.
- * @param type the object type.
- * @param name the object name. In system, the object's name must be unique.
+ * @param type is the object type.
+ *
+ * @param name is the object name. In system, the object's name must be unique.
  */
 void rt_object_init(struct rt_object         *object,
                     enum rt_object_class_type type,
@@ -361,8 +366,8 @@ void rt_object_init(struct rt_object         *object,
 }
 
 /**
- * This function will detach a static object from object system,
- * and the memory of static object is not freed.
+ * @brief This function will detach a static object from object system,
+ *        and the memory of static object is not freed.
  *
  * @param object the specified object to be detached.
  */
@@ -390,10 +395,11 @@ void rt_object_detach(rt_object_t object)
 
 #ifdef RT_USING_HEAP
 /**
- * This function will allocate an object from object system
+ * @brief This function will allocate an object from object system.
+ *
+ * @param type is the type of object.
  *
- * @param type the type of object
- * @param name the object name. In system, the object's name must be unique.
+ * @param name is the object name. In system, the object's name must be unique.
  *
  * @return object
  */
@@ -459,9 +465,9 @@ rt_object_t rt_object_allocate(enum rt_object_class_type type, const char *name)
 }
 
 /**
- * This function will delete an object and release object memory.
+ * @brief This function will delete an object and release object memory.
  *
- * @param object the specified object to be deleted.
+ * @param object is the specified object to be deleted.
  */
 void rt_object_delete(rt_object_t object)
 {
@@ -491,11 +497,12 @@ void rt_object_delete(rt_object_t object)
 #endif /* RT_USING_HEAP */
 
 /**
- * This function will judge the object is system object or not.
- * Normally, the system object is a static object and the type
- * of object set to RT_Object_Class_Static.
+ * @brief This function will judge the object is system object or not.
  *
- * @param object the specified object to be judged.
+ * @note  Normally, the system object is a static object and the type
+ *        of object set to RT_Object_Class_Static.
+ *
+ * @param object is the specified object to be judged.
  *
  * @return RT_TRUE if a system object, RT_FALSE for others.
  */
@@ -511,10 +518,10 @@ rt_bool_t rt_object_is_systemobject(rt_object_t object)
 }
 
 /**
- * This function will return the type of object without
- * RT_Object_Class_Static flag.
+ * @brief This function will return the type of object without
+ *        RT_Object_Class_Static flag.
  *
- * @param object the specified object to be get type.
+ * @param object is the specified object to be get type.
  *
  * @return the type of object.
  */
@@ -527,11 +534,12 @@ rt_uint8_t rt_object_get_type(rt_object_t object)
 }
 
 /**
- * This function will find specified name object from object
- * container.
+ * @brief This function will find specified name object from object
+ *        container.
+ *
+ * @param name is the specified name of object.
  *
- * @param name the specified name of object.
- * @param type the type of object
+ * @param type is the type of object
  *
  * @return the found object or RT_NULL if there is no this object
  * in object container.