update doxygen comments.

git-svn-id: https://rt-thread.googlecode.com/svn/trunk@1132 bbd45198-f89e-11dd-88c7-29a3b14d5316

11 files changed, 142 insertions, 86 deletions

diff --git a/src/device.c b/src/device.c
index c830ce6b1e..d8e467ee91 100644
--- a/src/device.c
+++ b/src/device.c
@@ -38,7 +38,7 @@ rt_err_t rt_device_register(rt_device_t dev, const char* name, rt_uint16_t flags
 }
 
 /**
- * This function removes a previouly registered device driver
+ * This function removes a previously registered device driver
  *
  * @param dev the pointer of device driver structure
  *
@@ -138,7 +138,7 @@ rt_device_t rt_device_find(const char* name)
 }
 
 /**
- * This function will initialize the speicial device
+ * This function will initialize the specified device
  *
  * @param dev the pointer of device driver structure
  * 
@@ -175,6 +175,7 @@ rt_err_t rt_device_init(rt_device_t dev)
  * This function will open a device
  *
  * @param dev the pointer of device driver structure
+ * @param oflag the flags for device open
  *
  * @return the result
  */
@@ -203,7 +204,7 @@ rt_err_t rt_device_open(rt_device_t dev, rt_uint16_t oflag)
 		}
 	}
 
-	/* device is a standalone device and opened */
+	/* device is a stand alone device and opened */
 	if ((dev->flag & RT_DEVICE_FLAG_STANDALONE) &&
 		(dev->open_flag & RT_DEVICE_OFLAG_OPEN))
 		return -RT_EBUSY;
@@ -269,6 +270,8 @@ rt_err_t rt_device_close(rt_device_t dev)
  * @param size the size of buffer
  *
  * @return the actually read size on successful, otherwise negative returned.
+ *
+ * @note since 0.4.0, the unit of size/pos is a block for block device.
  */
 rt_size_t rt_device_read (rt_device_t dev, rt_off_t pos, void* buffer, rt_size_t size)
 {
@@ -297,6 +300,8 @@ rt_size_t rt_device_read (rt_device_t dev, rt_off_t pos, void* buffer, rt_size_t
  * @param size the size of buffer
  *
  * @return the actually written size on successful, otherwise negative returned.
+ *
+ * @note since 0.4.0, the unit of size/pos is a block for block device.
  */
 rt_size_t rt_device_write(rt_device_t dev, rt_off_t pos, const void* buffer, rt_size_t size)
 {
@@ -341,6 +346,15 @@ rt_err_t rt_device_control(rt_device_t dev, rt_uint8_t cmd, void* arg)
 	return -RT_ENOSYS;
 }
 
+/**
+ * This function will set the indication callback function when device receives
+ * data.
+ *
+ * @param dev the pointer of device driver structure
+ * @param rx_ind the indication callback function
+ *
+ * @return RT_EOK
+ */
 rt_err_t rt_device_set_rx_indicate(rt_device_t dev, rt_err_t (*rx_ind )(rt_device_t dev, rt_size_t size))
 {
 	RT_ASSERT(dev != RT_NULL);
@@ -349,6 +363,15 @@ rt_err_t rt_device_set_rx_indicate(rt_device_t dev, rt_err_t (*rx_ind )(rt_devic
 	return RT_EOK;
 }
 
+/**
+ * This function will set the indication callback function when device has written
+ * data to physical hardware.
+ *
+ * @param dev the pointer of device driver structure
+ * @param tx_done the indication callback function
+ *
+ * @return RT_EOK
+ */
 rt_err_t rt_device_set_tx_complete(rt_device_t dev, rt_err_t (*tx_done)(rt_device_t dev, void *buffer))
 {
 	RT_ASSERT(dev != RT_NULL);
diff --git a/src/idle.c b/src/idle.c
index 2c0d9e0ba8..bb6edebfcc 100644
--- a/src/idle.c
+++ b/src/idle.c
@@ -54,7 +54,9 @@ void rt_thread_idle_sethook(void (*hook)())
 #endif
 
 /**
- * This function will do some things when system idle.
+ * @ingroup Thread
+ *
+ * This function will perform system background job when system idle.
  */
 void rt_thread_idle_excute(void)
 {
@@ -154,11 +156,8 @@ static void rt_thread_idle_entry(void* parameter)
 }
 
 /**
- * @addtogroup SystemInit
- */
-/*@{*/
-
-/**
+ * @ingroup SymstemInit
+ *
  * This function will initialize idle thread, then start it.
  *
  * @note this function must be invoked when system init.
@@ -175,5 +174,3 @@ void rt_thread_idle_init()
 	/* startup */
 	rt_thread_startup(&idle);
 }
-
-/*@}*/
diff --git a/src/kservice.c b/src/kservice.c
index 18ccb67525..af293cabd7 100644
--- a/src/kservice.c
+++ b/src/kservice.c
@@ -903,13 +903,13 @@ rt_int32_t rt_sprintf(char *buf ,const char *format,...)
 }
 
 /**
- * This function will set console to a device.
+ * This function will set a device as console device.
  * After set a device to console, all output of rt_kprintf will be
- * written to this device.
+ * redirected to this new device.
  *
- * @param device the new console device
+ * @param name the name of new console device
  *
- * @return the old console device
+ * @return the old console device handler
  */
 rt_device_t rt_console_set_device(const char* name)
 {
diff --git a/src/kservice.h b/src/kservice.h
index e862dd0f19..2e7e5015ed 100644
--- a/src/kservice.h
+++ b/src/kservice.h
@@ -24,6 +24,11 @@ extern "C" {
 #endif
 
 /**
+ * @addtogroup KernelService
+ */
+/*@{*/
+
+/**
  * @brief initialize a list
  *
  * @param l list to be initialized
@@ -93,6 +98,8 @@ rt_inline int rt_list_isempty(const rt_list_t *l)
 #define rt_list_entry(node, type, member) \
     ((type *)((char *)(node) - (unsigned long)(&((type *)0)->member)))
 
+/*@}*/
+
 #ifdef __cplusplus
 }
 #endif
diff --git a/src/mem.c b/src/mem.c
index 5bfc7b7d04..4afc7ebd96 100644
--- a/src/mem.c
+++ b/src/mem.c
@@ -229,7 +229,7 @@ void *rt_malloc(rt_size_t size)
 	if (size == 0) return RT_NULL;
 
 #ifdef RT_MEM_DEBUG
-	if (size != RT_ALIGN(size, RT_ALIGN_SIZE)
+	if (size != RT_ALIGN(size, RT_ALIGN_SIZE))
 		rt_kprintf("malloc size %d, but align to %d\n", size, RT_ALIGN(size, RT_ALIGN_SIZE));
 	else
 		rt_kprintf("malloc size %d\n", size);
diff --git a/src/mempool.c b/src/mempool.c
index 5d91118604..4232d38a3a 100644
--- a/src/mempool.c
+++ b/src/mempool.c
@@ -66,15 +66,16 @@ void rt_mp_free_sethook(void (*hook)(struct rt_mempool* mp, void *block))
 /*@{*/
 
 /**
- * This function will initialize a mempool object, normally which is used for static object.
+ * This function will initialize a memory pool object, normally which is used for
+ * static object.
  *
- * @param mp the mempool object
+ * @param mp the memory pool object
  * @param name the name of memory pool
  * @param start the star address of memory pool
  * @param size the total size of memory pool
  * @param block_size the size for each block
  *
- * @return the operation status, RT_EOK on OK; RT_ERROR on error
+ * @return RT_EOK
  *
  */
 rt_err_t rt_mp_init(struct rt_mempool* mp, const char* name, void *start, rt_size_t size, rt_size_t block_size)
@@ -117,6 +118,13 @@ rt_err_t rt_mp_init(struct rt_mempool* mp, const char* name, void *start, rt_siz
 	return RT_EOK;
 }
 
+/**
+ * This function will detach a memory pool from system object management.
+ *
+ * @param mp the memory pool object
+ *
+ * @return RT_EOK
+ */
 rt_err_t rt_mp_detach(struct rt_mempool* mp)
 {
 	struct rt_thread* thread;
@@ -217,7 +225,7 @@ rt_mp_t rt_mp_create(const char* name, rt_size_t block_count, rt_size_t block_si
  *
  * @param mp the memory pool object
  *
- * @return the operation status, RT_EOK on OK; -RT_ERROR on error
+ * @return RT_EOK
  *
  */
 rt_err_t rt_mp_delete(rt_mp_t mp)
@@ -276,7 +284,7 @@ rt_err_t rt_mp_delete(rt_mp_t mp)
  * @param mp the memory pool object
  * @param time the waiting time
  *
- * @return the allocated memory block
+ * @return the allocated memory block or RT_NULL on allocated failed
  *
  */
 void *rt_mp_alloc (rt_mp_t mp, rt_int32_t time)
diff --git a/src/module.c b/src/module.c
index ba64f3aa7c..721a408161 100644
--- a/src/module.c
+++ b/src/module.c
@@ -59,7 +59,7 @@ struct rt_module_symtab *_rt_module_symtab_begin = RT_NULL, *_rt_module_symtab_e
 /**
  * @ingroup SystemInit
  *
- * This function will init system module
+ * This function will initialize system module
  *
  */
 void rt_system_module_init(void)
@@ -171,61 +171,61 @@ static void rt_module_init_object_container(struct rt_module* module)
 {
 	RT_ASSERT(module != RT_NULL);
 
-	/* init object container - thread */
+	/* initialize object container - thread */
 	rt_list_init(&(module->module_object[RT_Object_Class_Thread].object_list));
 	module->module_object[RT_Object_Class_Thread].object_size = sizeof(struct rt_thread);
 	module->module_object[RT_Object_Class_Thread].type = RT_Object_Class_Thread;
 
 #ifdef RT_USING_SEMAPHORE
-	/* init object container - semaphore */
+	/* initialize object container - semaphore */
 	rt_list_init(&(module->module_object[RT_Object_Class_Semaphore].object_list));
 	module->module_object[RT_Object_Class_Semaphore].object_size = sizeof(struct rt_semaphore);
 	module->module_object[RT_Object_Class_Semaphore].type = RT_Object_Class_Semaphore;
 #endif
 
 #ifdef RT_USING_MUTEX
-	/* init object container - mutex */
+	/* initialize object container - mutex */
 	rt_list_init(&(module->module_object[RT_Object_Class_Mutex].object_list));
 	module->module_object[RT_Object_Class_Mutex].object_size = sizeof(struct rt_mutex);
 	module->module_object[RT_Object_Class_Mutex].type = RT_Object_Class_Mutex;
 #endif
 
 #ifdef RT_USING_EVENT
-	/* init object container - event */
+	/* initialize object container - event */
 	rt_list_init(&(module->module_object[RT_Object_Class_Event].object_list));
 	module->module_object[RT_Object_Class_Event].object_size = sizeof(struct rt_event);
 	module->module_object[RT_Object_Class_Event].type = RT_Object_Class_Event;
 #endif
 
 #ifdef RT_USING_MAILBOX
-	/* init object container - mailbox */
+	/* initialize object container - mailbox */
 	rt_list_init(&(module->module_object[RT_Object_Class_MailBox].object_list));
 	module->module_object[RT_Object_Class_MailBox].object_size = sizeof(struct rt_mailbox);
 	module->module_object[RT_Object_Class_MailBox].type = RT_Object_Class_MailBox;
 #endif
 
 #ifdef RT_USING_MESSAGEQUEUE
-	/* init object container - message queue */
+	/* initialize object container - message queue */
 	rt_list_init(&(module->module_object[RT_Object_Class_MessageQueue].object_list));
 	module->module_object[RT_Object_Class_MessageQueue].object_size = sizeof(struct rt_messagequeue);
 	module->module_object[RT_Object_Class_MessageQueue].type = RT_Object_Class_MessageQueue;
 #endif
 
 #ifdef RT_USING_MEMPOOL
-	/* init object container - memory pool */
+	/* initialize object container - memory pool */
 	rt_list_init(&(module->module_object[RT_Object_Class_MemPool].object_list));
 	module->module_object[RT_Object_Class_MemPool].object_size = sizeof(struct rt_mempool);
 	module->module_object[RT_Object_Class_MemPool].type = RT_Object_Class_MemPool;
 #endif
 
 #ifdef RT_USING_DEVICE
-	/* init object container - device */
+	/* initialize object container - device */
 	rt_list_init(&(module->module_object[RT_Object_Class_Device].object_list));
 	module->module_object[RT_Object_Class_Device].object_size = sizeof(struct rt_device);
 	module->module_object[RT_Object_Class_Device].type = RT_Object_Class_Device;
 #endif
 
-	/* init object container - timer */
+	/* initialize object container - timer */
 	rt_list_init(&(module->module_object[RT_Object_Class_Timer].object_list));
 	module->module_object[RT_Object_Class_Timer].object_size = sizeof(struct rt_timer);
 	module->module_object[RT_Object_Class_Timer].type = RT_Object_Class_Timer;
@@ -416,10 +416,9 @@ rt_module_t rt_module_load(const rt_uint8_t* name, void* module_ptr)
 #ifdef RT_USING_DFS
 #include <dfs_posix.h>
 /**
- * This function will load a module from file
+ * This function will load a module from a file
  *
- * @param name the name of module, which shall be unique
- * @param filename the file name of application module image
+ * @param filename the file name of application module
  *
  * @return the module object
  *
@@ -717,7 +716,7 @@ static struct rt_mem_head *morepage(rt_size_t nu)
 
 	RT_ASSERT (nu != 0);
 
-	/* alloc pages from system heap */
+	/* allocate pages from system heap */
 	npage = (nu * sizeof(struct rt_mem_head) + RT_MM_PAGE_SIZE - 1)/RT_MM_PAGE_SIZE;
 	cp = rt_page_alloc(npage);
 	if(!cp) return RT_NULL;
@@ -738,7 +737,7 @@ static struct rt_mem_head *morepage(rt_size_t nu)
 }
 
 /*
-  rt_module_malloc - alloc memory block in free list
+  rt_module_malloc - allocate memory block in free list
 */
 void *rt_module_malloc(rt_size_t size)
 {
@@ -753,14 +752,14 @@ void *rt_module_malloc(rt_size_t size)
 
 	prev = (struct rt_mem_head **)&rt_current_module->mem_list;
 
-	/* if size can be devided by page, alloc page directly */
+	/* if size can be divided by page, allocate page directly */
 	if(size % RT_MM_PAGE_SIZE == 0)
 	{
 		rt_uint8_t *cp;
 		struct rt_module_page *node;
 		rt_uint32_t npage = size / RT_MM_PAGE_SIZE;
 
-		/* alloc pages from system heap */
+		/* allocate pages from system heap */
 		cp = rt_page_alloc(npage);
 		if(!cp) return RT_NULL;
 
@@ -784,7 +783,7 @@ void *rt_module_malloc(rt_size_t size)
 		
 		if (b->size > nunits)
 		{
-			/* splite memory */
+			/* split memory */
 			n = b + nunits;
 			n->next = b->next;
 			n->size = b->size - nunits;
diff --git a/src/object.c b/src/object.c
index 56703d655a..65551ca6a7 100644
--- a/src/object.c
+++ b/src/object.c
@@ -26,40 +26,40 @@
 	{&(rt_object_container[c].object_list), &(rt_object_container[c].object_list)}
 struct rt_object_information rt_object_container[RT_Object_Class_Unknown] =
 {
-	/* init object container - thread */
+	/* initialize object container - thread */
 	{RT_Object_Class_Thread, _OBJ_CONTAINER_LIST_INIT(RT_Object_Class_Thread), sizeof(struct rt_thread)},
 #ifdef RT_USING_SEMAPHORE
-	/* init object container - semaphore */
+	/* initialize object container - semaphore */
 	{RT_Object_Class_Semaphore, _OBJ_CONTAINER_LIST_INIT(RT_Object_Class_Semaphore), sizeof(struct rt_semaphore)},
 #endif
 #ifdef RT_USING_MUTEX
-	/* init object container - mutex */
+	/* initialize object container - mutex */
 	{RT_Object_Class_Mutex, _OBJ_CONTAINER_LIST_INIT(RT_Object_Class_Mutex), sizeof(struct rt_mutex)},
 #endif
 #ifdef RT_USING_EVENT
-	/* init object container - event */
+	/* initialize object container - event */
 	{RT_Object_Class_Event, _OBJ_CONTAINER_LIST_INIT(RT_Object_Class_Event), sizeof(struct rt_event)},
 #endif
 #ifdef RT_USING_MAILBOX
-	/* init object container - mailbox */
+	/* initialize object container - mailbox */
 	{RT_Object_Class_MailBox, _OBJ_CONTAINER_LIST_INIT(RT_Object_Class_MailBox), sizeof(struct rt_mailbox)},
 #endif
 #ifdef RT_USING_MESSAGEQUEUE
-	/* init object container - message queue */
+	/* initialize object container - message queue */
 	{RT_Object_Class_MessageQueue, _OBJ_CONTAINER_LIST_INIT(RT_Object_Class_MessageQueue), sizeof(struct rt_messagequeue)},
 #endif
 #ifdef RT_USING_MEMPOOL
-	/* init object container - memory pool */
+	/* initialize object container - memory pool */
 	{RT_Object_Class_MemPool, _OBJ_CONTAINER_LIST_INIT(RT_Object_Class_MemPool), sizeof(struct rt_mempool)},
 #endif
 #ifdef RT_USING_DEVICE
-	/* init object container - device */
+	/* initialize object container - device */
 	{RT_Object_Class_Device, _OBJ_CONTAINER_LIST_INIT(RT_Object_Class_Device), sizeof(struct rt_device)},
 #endif
-	/* init object container - timer */
+	/* initialize object container - timer */
 	{RT_Object_Class_Timer, _OBJ_CONTAINER_LIST_INIT(RT_Object_Class_Timer), sizeof(struct rt_timer)},
 #ifdef RT_USING_MODULE
-	/* init object container - module */
+	/* initialize object container - module */
 	{RT_Object_Class_Module, _OBJ_CONTAINER_LIST_INIT(RT_Object_Class_Module), sizeof(struct rt_module)},
 #endif
 };
@@ -102,7 +102,7 @@ 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.
  *
- * The object is taken means that
+ * The object is taken means:
  * semaphore - semaphore is taken by thread
  * mutex - mutex is taken by thread
  * event - event is received by thread
@@ -120,7 +120,7 @@ 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.
  *
- * The object have been taken means that
+ * 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
@@ -152,8 +152,10 @@ void rt_object_put_sethook(void (*hook)(struct rt_object* object))
 /**
  * @ingroup SystemInit
  *
- * This function will initialize system object management
+ * This function will initialize system object management.
  *
+ * @deprecated since 0.3.0, this function does not need to be invoked
+ * in the system initialization.
  */
 void rt_system_object_init(void)
 {
@@ -165,12 +167,11 @@ void rt_system_object_init(void)
 /*@{*/
 
 /**
- * This function will init an object and add it to object system management.
+ * This function will initialize an object and add it to object system management.
  *
  * @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 name 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, const char* name)
 {
@@ -186,7 +187,7 @@ void rt_object_init(struct rt_object* object, enum rt_object_class_type type, co
 	information = &rt_object_container[type];
 #endif
 
-	/* init object's parameters */
+	/* initialize object's parameters */
 
 	/* set object type to static */
 	object->type = type | RT_Object_Class_Static;
@@ -272,7 +273,7 @@ rt_object_t rt_object_allocate(enum rt_object_class_type type, const char* name)
 		return RT_NULL;
 	}
 	
-	/* init object's parameters */
+	/* initialize object's parameters */
 
 	/* set object type */
 	object->type = type;
@@ -377,7 +378,7 @@ rt_err_t rt_object_is_systemobject(rt_object_t object)
  * @return the found object or RT_NULL if there is no this object
  * in object container.
  *
- * @note this routine only can be invoke in none-interrupt status.
+ * @note this function shall not be invoked in interrupt status.
  */
 rt_object_t rt_object_find(const char* name, rt_uint8_t type)
 {
diff --git a/src/scheduler.c b/src/scheduler.c
index 340c01bb27..ccc8f12ae9 100644
--- a/src/scheduler.c
+++ b/src/scheduler.c
@@ -119,7 +119,7 @@ static void _rt_scheduler_stack_check(struct rt_thread* thread)
 
 /**
  * @ingroup SystemInit
- * This function will init the system scheduler
+ * This function will initialize the system scheduler
  *
  */
 void rt_system_scheduler_init(void)
@@ -300,7 +300,7 @@ void rt_schedule()
     rt_hw_interrupt_enable(level);
 }
 
-/**
+/*
  * This function will insert a thread to system ready queue. The state of
  * thread will be set as READY and remove from suspend queue.
  *
@@ -341,7 +341,7 @@ void rt_schedule_insert_thread(struct rt_thread* thread)
     rt_hw_interrupt_enable(temp);
 }
 
-/**
+/*
  * This function will remove a thread from system ready queue.
  *
  * @param thread the thread to be removed
diff --git a/src/thread.c b/src/thread.c
index 544a295eaa..0f6b658ea6 100644
--- a/src/thread.c
+++ b/src/thread.c
@@ -96,7 +96,8 @@ static rt_err_t _rt_thread_init(struct rt_thread* thread,
 /*@{*/
 
 /**
- * This function will init a thread, normally it's used to initialize a static thread object.
+ * This function will initialize a thread, normally it's used to initialize a
+ * static thread object.
  *
  * @param thread the static thread object
  * @param name the name of thread, which shall be unique
@@ -107,7 +108,7 @@ static rt_err_t _rt_thread_init(struct rt_thread* thread,
  * @param priority the priority of thread
  * @param tick the time slice if there are same priority thread
  *
- * @return the operation status, RT_EOK on OK; -RT_ERROR on error
+ * @return the operation status, RT_EOK on OK, -RT_ERROR on error
  *
  */
 rt_err_t rt_thread_init(struct rt_thread* thread,
@@ -130,7 +131,8 @@ rt_err_t rt_thread_init(struct rt_thread* thread,
 
 #ifdef RT_USING_HEAP
 /**
- * This function will create a thread object and allocate thread object memory and stack.
+ * This function will create a thread object and allocate thread object memory
+ * and stack.
  *
  * @param name the name of thread, which shall be unique
  * @param entry the entry function of thread
@@ -186,7 +188,7 @@ rt_thread_t rt_thread_self (void)
  *
  * @param thread the thread to be started
  *
- * @return the operation status, RT_EOK on OK; -RT_ERROR on error
+ * @return the operation status, RT_EOK on OK, -RT_ERROR on error
  *
  */
 rt_err_t rt_thread_startup (rt_thread_t thread)
@@ -266,12 +268,12 @@ static void rt_thread_exit()
 }
 
 /**
- * This function will detach a thread. The thread object will be remove from thread
- * queue and detached/deleted from system object management.
+ * This function will detach a thread. The thread object will be removed from
+ * thread queue and detached/deleted from system object management.
  *
  * @param thread the thread to be deleted
  *
- * @return the operation status, RT_EOK on OK; -RT_ERROR on error
+ * @return the operation status, RT_EOK on OK, -RT_ERROR on error
  *
  */
 rt_err_t rt_thread_detach (rt_thread_t thread)
@@ -310,12 +312,12 @@ rt_err_t rt_thread_detach (rt_thread_t thread)
 
 #ifdef RT_USING_HEAP
 /**
- * This function will delete a thread. The thread object will be remove from thread
- * queue and detached/deleted from system object management.
+ * This function will delete a thread. The thread object will be removed from
+ * thread queue and detached/deleted from system object management.
  *
  * @param thread the thread to be deleted
  *
- * @return the operation status, RT_EOK on OK; -RT_ERROR on error
+ * @return the operation status, RT_EOK on OK, -RT_ERROR on error
  *
  */
 rt_err_t rt_thread_delete (rt_thread_t thread)
@@ -348,10 +350,11 @@ rt_err_t rt_thread_delete (rt_thread_t thread)
 #endif
 
 /**
- * This function will let current thread yield processor, and scheduler will get a highest thread to run.
- * After yield processor, the current thread is still in READY state.
+ * This function will let current thread yield processor, and scheduler will
+ * choose a highest thread to run. After yield processor, the current thread
+ * is still in READY state.
  *
- * @return the operation status, RT_EOK on OK; -RT_ERROR on error
+ * @return RT_EOK
  *
  */
 rt_err_t rt_thread_yield ()
@@ -394,7 +397,7 @@ rt_err_t rt_thread_yield ()
  *
  * @param tick the sleep ticks
  *
- * @return the operation status, RT_EOK on OK; RT_ERROR on error
+ * @return RT_EOK
  *
  */
 rt_err_t rt_thread_sleep (rt_tick_t tick)
@@ -432,7 +435,7 @@ rt_err_t rt_thread_sleep (rt_tick_t tick)
  *
  * @param tick the delay ticks
  *
- * @return the operation status, RT_EOK on OK; RT_ERROR on error
+ * @return RT_EOK
  *
  */
 rt_err_t rt_thread_delay(rt_tick_t tick)
@@ -440,6 +443,18 @@ rt_err_t rt_thread_delay(rt_tick_t tick)
 	return rt_thread_sleep(tick);
 }
 
+/**
+ * This function will control thread behaviors according to control command.
+ *
+ * @param thread the specified thread to be controlled
+ * @param cmd the control command, which includes
+ * 	RT_THREAD_CTRL_CHANGE_PRIORITY for changing priority level of thread;
+ *  RT_THREAD_CTRL_STARTUP for starting a thread;
+ *  RT_THREAD_CTRL_CLOSE for delete a thread.
+ * @param arg the argument of control command
+ *
+ * @return RT_EOK
+ */
 rt_err_t rt_thread_control (rt_thread_t thread, rt_uint8_t cmd, void* arg)
 {
 	register rt_base_t temp;
@@ -504,7 +519,7 @@ rt_err_t rt_thread_control (rt_thread_t thread, rt_uint8_t cmd, void* arg)
 		break;
 	}
 
-	return - RT_EOK;
+	return RT_EOK;
 }
 
 /**
@@ -512,8 +527,10 @@ rt_err_t rt_thread_control (rt_thread_t thread, rt_uint8_t cmd, void* arg)
  *
  * @param thread the thread to be suspended
  *
- * @return the operation status, RT_EOK on OK; -RT_ERROR on error
+ * @return the operation status, RT_EOK on OK, -RT_ERROR on error
  *
+ * @note if suspend self thread, after this function call, the
+ * rt_schedule() must be invoked.
  */
 rt_err_t rt_thread_suspend (rt_thread_t thread)
 {
@@ -552,7 +569,7 @@ rt_err_t rt_thread_suspend (rt_thread_t thread)
  *
  * @param thread the thread to be resumed
  *
- * @return the operation status, RT_EOK on OK; -RT_ERROR on error
+ * @return the operation status, RT_EOK on OK, -RT_ERROR on error
  *
  */
 rt_err_t rt_thread_resume (rt_thread_t thread)
@@ -596,8 +613,8 @@ rt_err_t rt_thread_resume (rt_thread_t thread)
 }
 
 /**
- * This function is the timeout function for thread, normally which will
- * be invoked when thread is timeout to wait some recourse.
+ * This function is the timeout function for thread, normally which is invoked
+ * when thread is timeout to wait some recourse.
  *
  * @param parameter the parameter of thread timeout function
  *
@@ -630,7 +647,9 @@ void rt_thread_timeout(void* parameter)
  *
  * @param name the name of thread finding
  *
- * @return the thread
+ * @return the found thread
+ *
+ * @note please don't invoke this function in interrupt status.
  */
 rt_thread_t rt_thread_find(char* name)
 {
diff --git a/src/timer.c b/src/timer.c
index b23e186ffc..b21a3016bd 100644
--- a/src/timer.c
+++ b/src/timer.c
@@ -199,7 +199,7 @@ rt_err_t rt_timer_delete(rt_timer_t timer)
  *
  * @param timer the timer to be started
  *
- * @return the operation status, RT_EOK on OK; RT_ERROR on error
+ * @return the operation status, RT_EOK on OK, -RT_ERROR on error
  *
  */
 rt_err_t rt_timer_start(rt_timer_t timer)
@@ -219,7 +219,8 @@ rt_err_t rt_timer_start(rt_timer_t timer)
 	/* disable interrupt */
 	level = rt_hw_interrupt_disable();
 
-	/* get timeout tick, which will wrap around if it reaches max ticks */
+	/* get timeout tick, the max timeout tick shall not great than RT_TICK_MAX/2 */
+	RT_ASSERT(timer->init_tick < RT_TICK_MAX/2);
 	timer->timeout_tick = rt_tick_get() + timer->init_tick;
 
 #ifdef RT_USING_TIMER_SOFT
@@ -267,7 +268,7 @@ rt_err_t rt_timer_start(rt_timer_t timer)
  *
  * @param timer the timer to be stopped
  *
- * @return the operation status, RT_EOK on OK; RT_ERROR on error
+ * @return the operation status, RT_EOK on OK, -RT_ERROR on error
  *
  */
 rt_err_t rt_timer_stop(rt_timer_t timer)
@@ -304,7 +305,7 @@ rt_err_t rt_timer_stop(rt_timer_t timer)
  * @param cmd the control command
  * @param arg the argument
  *
- * @return the operation status, RT_EOK on OK; RT_ERROR on error
+ * @return RT_EOK
  *
  */
 rt_err_t rt_timer_control(rt_timer_t timer, rt_uint8_t cmd, void* arg)
@@ -338,6 +339,7 @@ rt_err_t rt_timer_control(rt_timer_t timer, rt_uint8_t cmd, void* arg)
  * This function will check timer list, if a timeout event happens, the
  * corresponding timeout function will be invoked.
  *
+ * @note this function shall be invoked in operating system timer interrupt.
  */
 #ifdef RT_USING_TIMER_SOFT
 void  rt_soft_timer_tick_increase (void);