update doxygen comments.

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

components/dfs/src/dfs.c

@@ -35,6 +35,11 @@ struct dfs_fd fd_table[3 + DFS_FD_MAX];
 struct dfs_fd fd_table[DFS_FD_MAX];
 #endif
 
+/**
+ * @addtogroup DFS
+ */
+/*@{*/
+
 /**
  * this function will initialize device file system.
  */
@@ -60,7 +65,7 @@ void dfs_init()
 /**
  * this function will lock device file system.
  *
- * note: please don't invoke it on ISR.
+ * @note please don't invoke it on ISR.
  */
 void dfs_lock()
 {
@@ -73,7 +78,7 @@ void dfs_lock()
 /**
  * this function will lock device file system.
  *
- * note: please don't invoke it on ISR.
+ * @note please don't invoke it on ISR.
  */
 void dfs_unlock()
 {
@@ -81,7 +86,8 @@ void dfs_unlock()
 }
 
 /**
- * this function will allocate a file descriptor.
+ * @ingroup Fd
+ * This function will allocate a file descriptor.
  *
  * @return -1 on failed or the allocated file descriptor.
  */
@@ -120,7 +126,9 @@ __result:
 }
 
 /**
- * this function will return a file descriptor structure according to file 
+ * @ingroup Fd
+ *
+ * This function will return a file descriptor structure according to file
  * descriptor.
  *
  * @return NULL on on this file descriptor or the file descriptor structure
@@ -147,7 +155,9 @@ struct dfs_fd* fd_get(int fd)
 }
 
 /**
- * this function will put the file descriptor.
+ * @ingroup Fd
+ *
+ * This function will put the file descriptor.
  */
 void fd_put(struct dfs_fd* fd)
 {
@@ -163,11 +173,13 @@ void fd_put(struct dfs_fd* fd)
 };
 
 /** 
- * this function will return whether this file has been opend.
+ * @ingroup Fd
+ *
+ * This function will return whether this file has been opend.
  * 
  * @param pathname the file path name.
  *
- * @return 0 on file has been open, -1 on not open.
+ * @return 0 on file has been open successfully, -1 on open failed.
  */
 int fd_is_open(const char* pathname)
 {
@@ -337,3 +349,5 @@ up_one:
 	*dst = '\0';
 	return fullpath;
 }
+/*@}*/
+

components/dfs/src/dfs_file.c

@@ -16,6 +16,11 @@
 
 #define NO_WORKING_DIR	"system does not support working dir\n"
 
+/**
+ * @addtogroup FileApi
+ */
+/*@{*/
+
 /**
  * this function will open a file which specified by path with specified flags.
  *
@@ -530,3 +535,5 @@ void cat(const char* filename)
 FINSH_FUNCTION_EXPORT(cat, print file)
 
 #endif
+/* @} */
+

components/dfs/src/dfs_fs.c

@@ -15,6 +15,11 @@
 #include <dfs_fs.h>
 #include <dfs_file.h>
 
+/**
+ * @addtogroup FsApi
+ */
+/*@{*/
+
 /**
  * this function will register a file system instance to device file system.
  *
@@ -177,9 +182,10 @@ rt_err_t dfs_filesystem_get_partition(struct dfs_partition* part, rt_uint8_t* bu
  * this function will mount a file system on a specified path.
  *
  * @param device_name the name of device which includes a file system.
+ * @param path the path to mount a file system
  * @param filesystemtype the file system type
  * @param rwflag the read/write etc. flag.
- * @param data the privated data(parameter) for this file system.
+ * @param data the private data(parameter) for this file system.
  *
  * @return 0 on successful or -1 on failed.
  */
@@ -368,8 +374,8 @@ err1:
 /**
  * make a file system on the special device
  *
- * @param fs_name, the file system name
- * @param device_name, the special device name
+ * @param fs_name the file system name
+ * @param device_name the special device name
  *
  * @return 0 on successful, otherwise failed.
  */
@@ -442,3 +448,4 @@ void df(const char* path)
 FINSH_FUNCTION_EXPORT(df, get disk free);
 #endif
 
+/* @} */

components/dfs/src/dfs_posix.c

@@ -15,6 +15,11 @@
 #include <dfs.h>
 #include <dfs_posix.h>
 
+/**
+ * @addtogroup FsPosixApi
+ */
+/*@{*/
+
 /**
  * this function is a POSIX compliant version, which will open a file and return
  * a file descriptor.
@@ -165,7 +170,7 @@ int write(int fd, const void *buf, size_t len)
  *
  * @param fd the file descriptor.
  * @param offset the offset to be seeked.
- * @param dir the directory of seek.
+ * @param whence the directory of seek.
  *
  * @return the current file position, or -1 on failed.
  */
@@ -627,7 +632,7 @@ int chdir(const char *path)
  * working directory.
  *
  * @param buf the returned current directory.
- * @size the buffer size.
+ * @param size the buffer size.
  *
  * @return the returned current directory.
  */
@@ -643,3 +648,4 @@ char *getcwd(char *buf, size_t size)
 	return buf;
 }
 
+/* @} */

components/finsh/finsh.h

@@ -51,13 +51,6 @@
 
 /* -- the end of option -- */
 
- /**
- * @defgroup finsh finsh shell
- *
- * finsh is a C-expression shell which gives user access to some symbols present in RT-Thread.
- */
-/*@{*/
-
 #if defined(RT_USING_NEWLIB) || defined (RT_USING_MINILIBC)
 #include <sys/types.h>
 #include <string.h>
@@ -94,22 +87,26 @@ int atoi(const char* s);
 #define FINSH_VERSION_MAJOR			0
 #define FINSH_VERSION_MINOR			5
 
-/* error code */
-#define FINSH_ERROR_OK              0   /** No error */
-#define FINSH_ERROR_INVALID_TOKEN	1	/**  Invalid token */
-#define FINSH_ERROR_EXPECT_TYPE		2	/** Expect a type */
-#define FINSH_ERROR_UNKNOWN_TYPE	3	/** Unknown type */
-#define FINSH_ERROR_VARIABLE_EXIST	4	/** Variable exist */
-#define FINSH_ERROR_EXPECT_OPERATOR	5	/** Expect a operater */
-#define FINSH_ERROR_MEMORY_FULL		6	/** Memory full */
-#define FINSH_ERROR_UNKNOWN_OP		7 	/** Unknown operator */
-#define FINSH_ERROR_UNKNOWN_NODE	8	/** Unknown node */
-#define FINSH_ERROR_EXPECT_CHAR		9	/** Expect a character */
-#define FINSH_ERROR_UNEXPECT_END	10	/** Unexpect end */
-#define FINSH_ERROR_UNKNOWN_TOKEN	11	/** Unknown token */
-#define FINSH_ERROR_NO_FLOAT		12	/** Float not supported */
-#define FINSH_ERROR_UNKNOWN_SYMBOL	13	/** Unknown symbol */
-#define FINSH_ERROR_NULL_NODE		14	/** Null node */
+/**
+ * @addtogroup finsh
+ */
+/*@{*/
+#define FINSH_ERROR_OK              0   /**< No error 			*/
+#define FINSH_ERROR_INVALID_TOKEN	1	/**< Invalid token 		*/
+#define FINSH_ERROR_EXPECT_TYPE		2	/**< Expect a type 		*/
+#define FINSH_ERROR_UNKNOWN_TYPE	3	/**< Unknown type 		*/
+#define FINSH_ERROR_VARIABLE_EXIST	4	/**< Variable exist 	*/
+#define FINSH_ERROR_EXPECT_OPERATOR	5	/**< Expect a operator 	*/
+#define FINSH_ERROR_MEMORY_FULL		6	/**< Memory full 		*/
+#define FINSH_ERROR_UNKNOWN_OP		7 	/**< Unknown operator 	*/
+#define FINSH_ERROR_UNKNOWN_NODE	8	/**< Unknown node 		*/
+#define FINSH_ERROR_EXPECT_CHAR		9	/**< Expect a character */
+#define FINSH_ERROR_UNEXPECT_END	10	/**< Unexpect end 		*/
+#define FINSH_ERROR_UNKNOWN_TOKEN	11	/**< Unknown token 		*/
+#define FINSH_ERROR_NO_FLOAT		12	/**< Float not supported */
+#define FINSH_ERROR_UNKNOWN_SYMBOL	13	/**< Unknown symbol 	*/
+#define FINSH_ERROR_NULL_NODE		14	/**< Null node 			*/
+/*@}*/
 
 typedef long (*syscall_func)();
 
@@ -158,6 +155,14 @@ struct finsh_sysvar* finsh_sysvar_lookup(const char* name);
 
 #ifdef FINSH_USING_SYMTAB
 	#ifdef FINSH_USING_DESCRIPTION
+		/**
+		 * @ingroup finsh
+		 *
+		 * This macro exports a system function to finsh shell.
+		 *
+		 * @param name the name of function.
+		 * @param desc the description of function, which will show in help.
+		 */
 		#define FINSH_FUNCTION_EXPORT(name, desc)					 \
 		const char __fsym_##name##_name[] = #name;					 \
 		const char __fsym_##name##_desc[] = #desc;					 \
@@ -168,6 +173,15 @@ struct finsh_sysvar* finsh_sysvar_lookup(const char* name);
 			(syscall_func)&name		\
 		};
 
+		/**
+		 * @ingroup finsh
+		 *
+		 * This macro exports a variable to finsh shell.
+		 *
+		 * @param name the name of function.
+		 * @param type the type of variable.
+		 * @param desc the description of function, which will show in help.
+		 */
 		#define FINSH_VAR_EXPORT(name, type, desc)					\
 		const char __vsym_##name##_name[] = #name;					\
 		const char __vsym_##name##_desc[] = #desc;					\
@@ -257,24 +271,27 @@ struct finsh_parser
 };
 
 /**
- * finsh basic data type
+ * @ingroup finsh
+ *
+ * The basic data type in finsh shell
  */
+
 enum finsh_type {
-	finsh_type_unknown = 0,
-	finsh_type_void,		/** void  			*/
-	finsh_type_voidp,		/** void pointer  	*/
-	finsh_type_char,		/** char  			*/
-	finsh_type_uchar,		/** unsigned char  	*/
-	finsh_type_charp,		/** char pointer  	*/
-	finsh_type_short,		/** short  			*/
-	finsh_type_ushort,		/** unsigned short 	*/
-	finsh_type_shortp,		/** short pointer  	*/
-	finsh_type_int,			/** int 			*/
-	finsh_type_uint,		/** unsigned int 	*/
-	finsh_type_intp,		/** int pointer 	*/
-	finsh_type_long,		/** long 			*/
-	finsh_type_ulong,		/** unsigned long 	*/
-	finsh_type_longp		/** long pointer 	*/
+	finsh_type_unknown = 0, /**< unknown data type */
+	finsh_type_void,		/**< void  			*/
+	finsh_type_voidp,		/**< void pointer  	*/
+	finsh_type_char,		/**< char  			*/
+	finsh_type_uchar,		/**< unsigned char  */
+	finsh_type_charp,		/**< char pointer  	*/
+	finsh_type_short,		/**< short  		*/
+	finsh_type_ushort,		/**< unsigned short */
+	finsh_type_shortp,		/**< short pointer  */
+	finsh_type_int,			/**< int 			*/
+	finsh_type_uint,		/**< unsigned int 	*/
+	finsh_type_intp,		/**< int pointer 	*/
+	finsh_type_long,		/**< long 			*/
+	finsh_type_ulong,		/**< unsigned long 	*/
+	finsh_type_longp		/**< long pointer 	*/
 };
 
 /* init finsh environment */
@@ -284,7 +301,6 @@ int finsh_flush(struct finsh_parser* parser);
 /* reset all of finsh */
 int finsh_reset(struct finsh_parser* parser);
 #ifdef RT_USING_DEVICE
-/* set finsh device */
 void finsh_set_device(const char* device_name);
 #endif
 
@@ -307,13 +323,18 @@ const char* finsh_error_string(u_char type);
 
 #ifdef RT_USING_HEAP
 /**
- * append a system call to finsh runtime environment
+ * @ingroup finsh
+ *
+ * This function appends a system call to finsh runtime environment
  * @param name the name of system call
  * @param func the function pointer of system call
  */
 void finsh_syscall_append(const char* name, syscall_func func);
+
 /**
- * append a system variable to finsh runtime environment
+ * @ingroup finsh
+ *
+ * This function appends a system variable to finsh runtime environment
  * @param name the name of system variable
  * @param type the data type of system variable
  * @param addr the address of system variable
@@ -321,6 +342,4 @@ void finsh_syscall_append(const char* name, syscall_func func);
 void finsh_sysvar_append(const char* name, u_char type, void* addr);
 #endif
 
-/*@}*/
-
 #endif

components/finsh/shell.c

@@ -94,6 +94,13 @@ static rt_err_t finsh_rx_ind(rt_device_t dev, rt_size_t size)
 	return RT_EOK;
 }
 
+/**
+ * @ingroup finsh
+ *
+ * This function sets the input device of finsh shell.
+ *
+ * @param device_name the name of new input device.
+ */
 void finsh_set_device(const char* device_name)
 {
 	rt_device_t dev = RT_NULL;
@@ -117,18 +124,41 @@ void finsh_set_device(const char* device_name)
 	}
 }
 
+/**
+ * @ingroup finsh
+ *
+ * This function returns current finsh shell input device.
+ *
+ * @return the finsh shell input device name is returned.
+ */
 const char* finsh_get_device()
 {
 	RT_ASSERT(shell != RT_NULL);
 	return shell->device->parent.name;
 }
 
-void finsh_set_echo(rt_uint32_t enable)
+/**
+ * @ingroup finsh
+ *
+ * This function set the echo mode of finsh shell.
+ *
+ * FINSH_OPTION_ECHO=0x01 is echo mode, other values are none-echo mode.
+ *
+ * @param echo the echo mode
+ */
+void finsh_set_echo(rt_uint32_t echo)
 {
 	RT_ASSERT(shell != RT_NULL);
-	shell->echo_mode = enable;
+	shell->echo_mode = echo;
 }
 
+/**
+ * @ingroup finsh
+ *
+ * This function gets the echo mode of finsh shell.
+ *
+ * @return the echo mode
+ */
 rt_uint32_t finsh_get_echo()
 {
 	RT_ASSERT(shell != RT_NULL);
@@ -406,7 +436,12 @@ void finsh_system_var_init(void* begin, void* end)
     #pragma section="VSymTab"
   #endif
 #endif
-/* init finsh */
+
+/*
+ * @ingroup finsh
+ *
+ * This function will initialize finsh shell
+ */
 void finsh_system_init(void)
 {
 	rt_err_t result;

components/finsh/shell.h

@@ -51,9 +51,10 @@ struct finsh_shell
 	rt_device_t device;
 };
 
-void finsh_set_echo(rt_uint32_t enable);
+void finsh_set_echo(rt_uint32_t echo);
 rt_uint32_t finsh_get_echo(void);
 
 void finsh_set_device(const char* device_name);
+const char* finsh_get_device();
 
 #endif

components/libc/newlib/libc.c

@@ -99,6 +99,10 @@ void libc_system_init(const char* tty_name)
 	int fd;
 	extern int pthread_system_init(void);
 
+#ifndef RT_USING_DFS_DEVFS
+#error Please enable devfs by defining RT_USING_DFS_DEVFS in rtconfig.h
+#endif
+
 	/* init console device */
 	rt_console_init(tty_name);
 

include/rtdef.h

@@ -23,35 +23,46 @@
 extern "C" {
 #endif
 
-/* RT-Thread version information */
-#define RT_VERSION						4L
-#define RT_SUBVERSION					0L
-
-/* date type defination					*/
-typedef signed 	 char  					rt_int8_t;
-typedef signed 	 short 					rt_int16_t;
-typedef signed 	 long  					rt_int32_t;
-typedef unsigned char  					rt_uint8_t;
-typedef unsigned short 					rt_uint16_t;
-typedef unsigned long  					rt_uint32_t;
-typedef int 							rt_bool_t;
+/**
+ * @addtogroup BasicDef
+ */
+/*@{*/
+
+/**
+ * RT-Thread version information
+ */
+#define RT_VERSION						4L		/**< major version number */
+#define RT_SUBVERSION					0L		/**< minor version number */
+
+/**
+ * RT-Thread basic data type definitions
+ */
+typedef signed 	 char  					rt_int8_t;		/**<  8bit integer type */
+typedef signed 	 short 					rt_int16_t;		/**< 16bit integer type */
+typedef signed 	 long  					rt_int32_t;		/**< 32bit integer type */
+typedef unsigned char  					rt_uint8_t;		/**<  8bit unsigned integer type */
+typedef unsigned short 					rt_uint16_t;	/**< 16bit unsigned integer type */
+typedef unsigned long  					rt_uint32_t;	/**< 32bit unsigned integer type */
+typedef int 							rt_bool_t;		/**< boolean type */
 
 /* 32bit CPU */
-typedef long 							rt_base_t;
-typedef unsigned long 					rt_ubase_t;
-
-/* RT-Thread definitions */
-typedef rt_base_t						rt_err_t;		/* Type for error number.					*/
-typedef rt_uint32_t						rt_time_t;		/* Type for time stamp. 					*/
-typedef rt_uint32_t						rt_tick_t;		/* Type for tick count. 					*/
-typedef rt_base_t						rt_flag_t;		/* Type for flags. 							*/
-typedef rt_ubase_t						rt_size_t;		/* Type for size number.					*/
-typedef rt_ubase_t						rt_dev_t;		/* Type for device.							*/
-typedef rt_uint32_t						rt_off_t;		/* Type for offset.							*/
-
-/* RT-Thread bool type definitions 		*/
-#define RT_TRUE 						1
-#define RT_FALSE 						0
+typedef long 							rt_base_t;		/**< Nbit CPU related date type */
+typedef unsigned long 					rt_ubase_t;		/**< Nbit unsigned CPU related data type */
+
+typedef rt_base_t						rt_err_t;		/**< Type for error number		*/
+typedef rt_uint32_t						rt_time_t;		/**< Type for time stamp 		*/
+typedef rt_uint32_t						rt_tick_t;		/**< Type for tick count 		*/
+typedef rt_base_t						rt_flag_t;		/**< Type for flags 			*/
+typedef rt_ubase_t						rt_size_t;		/**< Type for size number		*/
+typedef rt_ubase_t						rt_dev_t;		/**< Type for device			*/
+typedef rt_uint32_t						rt_off_t;		/**< Type for offset			*/
+
+/**
+ * boolean type definitions
+ */
+#define RT_TRUE 						1	/**< boolean true  */
+#define RT_FALSE 						0	/**< boolean fails */
+/*@}*/
 
 /* maximun value of base type 			*/
 #define RT_UINT8_MAX					0xff			/* Maxium number of UINT8.					*/
@@ -118,15 +129,15 @@ typedef rt_uint32_t						rt_off_t;		/* Type for offset.							*/
  * @addtogroup Error
  */
 /*@{*/
-/* RT-Thread error code definitions */
-#define RT_EOK							0				/* There is no error 						*/
-#define RT_ERROR						1				/* A generic error happens 					*/
-#define RT_ETIMEOUT						2				/* Timed out 								*/
-#define RT_EFULL						3				/* The resource is full						*/
-#define RT_EEMPTY						4				/* The resource is empty 					*/
-#define RT_ENOMEM						5				/* No memory								*/
-#define RT_ENOSYS						6				/* No system 								*/
-#define RT_EBUSY						7				/* Busy										*/
+/** RT-Thread error code definitions */
+#define RT_EOK							0				/**< There is no error 					*/
+#define RT_ERROR						1				/**< A generic error happens 			*/
+#define RT_ETIMEOUT						2				/**< Timed out 							*/
+#define RT_EFULL						3				/**< The resource is full				*/
+#define RT_EEMPTY						4				/**< The resource is empty 				*/
+#define RT_ENOMEM						5				/**< No memory							*/
+#define RT_ENOSYS						6				/**< No system 							*/
+#define RT_EBUSY						7				/**< Busy								*/
 /*@}*/
 
 #ifdef RT_DEBUG
@@ -137,18 +148,25 @@ typedef rt_uint32_t						rt_off_t;		/* Type for offset.							*/
 #endif
 
 /**
+ * @ingroup BasicDef
+ *
  * @def RT_ALIGN(size, align)
  * Return the most contiguous size aligned at specified width. RT_ALIGN(13, 4)
  * would return 16.
+ */
+#define RT_ALIGN(size, align)			(((size) + (align) - 1) & ~((align)-1))
+/**
+ * @ingroup BasicDef
  *
  * @def RT_ALIGN_DOWN(size, align)
  * Return the down number of aligned at specified width. RT_ALIGN_DOWN(13, 4)
  * would return 12. 
  */
-#define RT_ALIGN(size, align)			(((size) + (align) - 1) & ~((align)-1))
 #define RT_ALIGN_DOWN(size, align)		((size) & ~((align) -1))
 
 /**
+ * @ingroup BasicDef
+ *
  * @def RT_NULL
  * Similar as the \c NULL in C library.
  */
@@ -171,25 +189,19 @@ typedef struct rt_list_node rt_list_t;					/* Type for lists. 							*/
  */
 #define RT_OBJECT_FLAG_MODULE		0x80			/* is module object. 						*/
 
-/*
+/**
  * Base structure of Kernel object
  */
 struct rt_object
 {
-	/* name of kernel object			*/
-	char      	name[RT_NAME_MAX];
-	/* type of kernel object 			*/
-	rt_uint8_t  type;
-	/* flag of kernel object			*/
-	rt_uint8_t  flag;
-	
-#ifdef RT_USING_MODULE
-	/* id of application module			*/
-	void* module_id;
-#endif	
+	char      	name[RT_NAME_MAX];						/**< name of kernel object					*/
+	rt_uint8_t  type;									/**< type of kernel object 					*/
+	rt_uint8_t  flag;									/**< flag of kernel object					*/
 
-	/* list pointer of kernel object 	*/
-	rt_list_t	list;
+#ifdef RT_USING_MODULE
+	void* module_id;									/**< id of application module				*/
+#endif
+	rt_list_t	list;									/**< list node of kernel object 			*/
 };
 typedef struct rt_object* rt_object_t;					/* Type for kernel objects. 				*/
 
@@ -197,7 +209,6 @@ typedef struct rt_object* rt_object_t;					/* Type for kernel objects. 				*/
  *	The object type can be one of the follows with specific
  *	macros enabled:
  *	- Thread
- *	- Process
  *	- Semaphore
  *	- Mutex
  *	- Event
@@ -211,44 +222,44 @@ typedef struct rt_object* rt_object_t;					/* Type for kernel objects. 				*/
  */
 enum rt_object_class_type
 {
-	RT_Object_Class_Thread = 0,							/* The object is a thread. 					*/
+	RT_Object_Class_Thread = 0,							/**< The object is a thread. 				*/
 #ifdef RT_USING_SEMAPHORE
-	RT_Object_Class_Semaphore,							/* The object is a semaphore. 				*/
+	RT_Object_Class_Semaphore,							/**< The object is a semaphore. 			*/
 #endif
 #ifdef RT_USING_MUTEX
-	RT_Object_Class_Mutex,								/* The object is a mutex. 					*/
+	RT_Object_Class_Mutex,								/**< The object is a mutex. 				*/
 #endif
 #ifdef RT_USING_EVENT
-	RT_Object_Class_Event,								/* The object is a event. 					*/
+	RT_Object_Class_Event,								/**< The object is a event. 				*/
 #endif
 #ifdef RT_USING_MAILBOX
-	RT_Object_Class_MailBox,							/* The object is a mail box. 				*/
+	RT_Object_Class_MailBox,							/**< The object is a mail box. 				*/
 #endif
 #ifdef RT_USING_MESSAGEQUEUE
-	RT_Object_Class_MessageQueue,						/* The object is a message queue. 			*/
+	RT_Object_Class_MessageQueue,						/**< The object is a message queue. 		*/
 #endif
 #ifdef RT_USING_MEMPOOL
-	RT_Object_Class_MemPool,							/* The object is a memory pool. 			*/
+	RT_Object_Class_MemPool,							/**< The object is a memory pool. 			*/
 #endif
 #ifdef RT_USING_DEVICE
-	RT_Object_Class_Device,								/* The object is a device 					*/
+	RT_Object_Class_Device,								/**< The object is a device 				*/
 #endif
-	RT_Object_Class_Timer,								/* The object is a timer. 					*/
+	RT_Object_Class_Timer,								/**< The object is a timer. 				*/
 #ifdef RT_USING_MODULE
-	RT_Object_Class_Module,								/* The object is a module. 					*/
+	RT_Object_Class_Module,								/**< The object is a module. 				*/
 #endif
-	RT_Object_Class_Unknown,							/* The object is unknown. 					*/
-	RT_Object_Class_Static = 0x80						/* The object is a static object. 			*/
+	RT_Object_Class_Unknown,							/**< The object is unknown. 				*/
+	RT_Object_Class_Static = 0x80						/**< The object is a static object. 		*/
 };
 
-/*
- * the information of the kernel object
+/**
+ * The information of the kernel object
  */
 struct rt_object_information
 {
-	enum rt_object_class_type type;						/* object class type. 						*/
-	rt_list_t object_list;								/* object list. 							*/
-	rt_size_t object_size;								/* object size. 							*/
+	enum rt_object_class_type type;						/**< object class type 						*/
+	rt_list_t object_list;								/**< object list 							*/
+	rt_size_t object_size;								/**< object size 							*/
 };
 /*@}*/
 
@@ -257,37 +268,36 @@ struct rt_object_information
  */
 /*@{*/
 
-/*
+/**
  * clock & timer macros
  */
-#define RT_TIMER_FLAG_DEACTIVATED		0x0				/* timer is deactive. 						*/
-#define RT_TIMER_FLAG_ACTIVATED			0x1				/* timer is active. 						*/
-#define RT_TIMER_FLAG_ONE_SHOT			0x0				/* one shot timer. 							*/
-#define RT_TIMER_FLAG_PERIODIC			0x2				/* periodic timer. 							*/
+#define RT_TIMER_FLAG_DEACTIVATED		0x0				/**< timer is deactive 						*/
+#define RT_TIMER_FLAG_ACTIVATED			0x1				/**< timer is active 						*/
+#define RT_TIMER_FLAG_ONE_SHOT			0x0				/**< one shot timer							*/
+#define RT_TIMER_FLAG_PERIODIC			0x2				/**< periodic timer 						*/
 
-#define RT_TIMER_FLAG_HARD_TIMER		0x0				/* hard timer,the timer's callback function will be called in tick isr. 	*/
-#define RT_TIMER_FLAG_SOFT_TIMER		0x4				/* soft timer,the timer's callback function will be called in timer thread. */
+#define RT_TIMER_FLAG_HARD_TIMER		0x0				/**< hard timer,the timer's callback function will be called in tick isr. 	*/
+#define RT_TIMER_FLAG_SOFT_TIMER		0x4				/**< soft timer,the timer's callback function will be called in timer thread. */
 
-#define RT_TIMER_CTRL_SET_TIME			0x0				/* set timer. 								*/
-#define RT_TIMER_CTRL_GET_TIME			0x1				/* get timer. 								*/
-#define RT_TIMER_CTRL_SET_ONESHOT		0x2				/* change timer to one shot. 				*/
-#define RT_TIMER_CTRL_SET_PERIODIC		0x3				/* change timer to periodic. 				*/
+#define RT_TIMER_CTRL_SET_TIME			0x0				/**< set timer control command 				*/
+#define RT_TIMER_CTRL_GET_TIME			0x1				/**< get timer control command 				*/
+#define RT_TIMER_CTRL_SET_ONESHOT		0x2				/**< change timer to one shot 				*/
+#define RT_TIMER_CTRL_SET_PERIODIC		0x3				/**< change timer to periodic 				*/
 
-/*
+/**
  * timer structure
- *
  */
 struct rt_timer
 {
-	struct rt_object parent;
+	struct rt_object parent;							/**< inherit from rt_object 				*/
 
-	rt_list_t list;										/* the node of timer list. 					*/
+	rt_list_t list;										/**< the node of timer list 				*/
 
-	void (*timeout_func)(void* parameter);				/* timeout function. 						*/
-	void *parameter;									/* timeout function's parameter. 			*/
+	void (*timeout_func)(void* parameter);				/**< timeout function 						*/
+	void *parameter;									/**< timeout function's parameter 			*/
 
-	rt_tick_t init_tick;								/* timer timeout tick. 						*/
-	rt_tick_t timeout_tick;								/* timeout tick. 							*/
+	rt_tick_t init_tick;								/**< timer timeout tick						*/
+	rt_tick_t timeout_tick;								/**< timeout tick 							*/
 };
 typedef struct rt_timer* rt_timer_t;
 /*@}*/
@@ -301,53 +311,59 @@ typedef struct rt_timer* rt_timer_t;
  * Thread
  */
 
-/* thread state definitions */
-#define RT_THREAD_INIT					0x00				/* Inited. 									*/
-#define RT_THREAD_READY					0x01				/* Ready. 									*/
-#define RT_THREAD_SUSPEND				0x02				/* Suspend. 								*/
-#define RT_THREAD_RUNNING				0x03				/* Running. 								*/
-#define RT_THREAD_BLOCK					RT_THREAD_SUSPEND	/* Blocked. 								*/
-#define RT_THREAD_CLOSE					0x04				/* Closed. 									*/
+/*
+ * thread state definitions
+ */
+#define RT_THREAD_INIT					0x00				/**< Initialized status					*/
+#define RT_THREAD_READY					0x01				/**< Ready status						*/
+#define RT_THREAD_SUSPEND				0x02				/**< Suspend status						*/
+#define RT_THREAD_RUNNING				0x03				/**< Running status						*/
+#define RT_THREAD_BLOCK					RT_THREAD_SUSPEND	/**< Blocked status 					*/
+#define RT_THREAD_CLOSE					0x04				/**< Closed status						*/
 
-#define RT_THREAD_CTRL_STARTUP			0x00			/* Starup thread. 							*/
-#define RT_THREAD_CTRL_CLOSE			0x01			/* Close thread. 							*/
-#define RT_THREAD_CTRL_CHANGE_PRIORITY	0x02			/* Change thread priority. 					*/
-#define RT_THREAD_CTRL_INFO				0x03			/* Get thread information. 					*/
+/**
+ * thread control command definitions
+ */
+#define RT_THREAD_CTRL_STARTUP			0x00				/**< Starup thread. 					*/
+#define RT_THREAD_CTRL_CLOSE			0x01				/**< Close thread. 						*/
+#define RT_THREAD_CTRL_CHANGE_PRIORITY	0x02				/**< Change thread priority. 			*/
+#define RT_THREAD_CTRL_INFO				0x03				/**< Get thread information. 			*/
 
 typedef struct rt_thread* rt_thread_t;
 
-/*
- * Thread related structure
+/**
+ * Thread structure
+ *
  */
 struct rt_thread
 {
 	/* rt object */
-	char        name[RT_NAME_MAX];						/* the name of thread 						*/
-	rt_uint8_t	type;									/* type of object 							*/
-	rt_uint8_t  flags;									/* thread's flags 							*/
+	char        name[RT_NAME_MAX];						/**< the name of thread 					*/
+	rt_uint8_t	type;									/**< type of object 						*/
+	rt_uint8_t  flags;									/**< thread's flags 						*/
 	
 #ifdef RT_USING_MODULE
-	void* 		module_id;								/* id of application module					*/
+	void* 		module_id;								/**< id of application module				*/
 #endif
 
-	rt_list_t	list;									/* the object list 							*/
-	rt_list_t	tlist;									/* the thread list 							*/
+	rt_list_t	list;									/**< the object list 						*/
+	rt_list_t	tlist;									/**< the thread list 						*/
 
 	/* stack point and entry */
-	void*		sp;										/* stack point 								*/
-	void*		entry;									/* entry 									*/
-	void*       parameter;								/* parameter 								*/
-	void*       stack_addr;								/* stack address 							*/
-	rt_uint16_t stack_size;								/* stack size 								*/
+	void*		sp;										/**< stack point 							*/
+	void*		entry;									/**< entry 									*/
+	void*       parameter;								/**< parameter 								*/
+	void*       stack_addr;								/**< stack address 							*/
+	rt_uint16_t stack_size;								/**< stack size 							*/
 
 	/* error code */
-	rt_err_t    error;									/* error code 								*/
+	rt_err_t    error;									/**< error code 							*/
 
-	rt_uint8_t	stat;									/* thread stat 								*/
+	rt_uint8_t	stat;									/**< thread stat 							*/
 
 	/* priority */
-	rt_uint8_t	current_priority;						/* current priority 						*/
-	rt_uint8_t	init_priority;							/* initialized priority 					*/
+	rt_uint8_t	current_priority;						/**< current priority 						*/
+	rt_uint8_t	init_priority;							/**< initialized priority 					*/
 #if RT_THREAD_PRIORITY_MAX > 32
 	rt_uint8_t 	number;
 	rt_uint8_t	high_mask;
@@ -360,14 +376,14 @@ struct rt_thread
 	rt_uint8_t	event_info;
 #endif
 
-	rt_ubase_t	init_tick;								/* thread's tick 							*/
-	rt_ubase_t 	remaining_tick;							/* remaining tick 							*/
+	rt_ubase_t	init_tick;								/**< thread's initialized tick 				*/
+	rt_ubase_t 	remaining_tick;							/**< remaining tick 						*/
 
-	struct rt_timer thread_timer;						/* thread timer 							*/
+	struct rt_timer thread_timer;						/**< thread timer 							*/
 
-	void 		(*cleanup)(struct rt_thread* tid);		/* cleanup function when thread exit 		*/
+	void 		(*cleanup)(struct rt_thread* tid);		/**< cleanup function when thread exit 		*/
 
-	rt_uint32_t user_data;								/* user data 								*/
+	rt_uint32_t user_data;								/**< user data 								*/
 };
 /*@}*/
 
@@ -375,117 +391,117 @@ struct rt_thread
  * @addtogroup IPC
  */
 /*@{*/
-/*
- * ipc & sync
+
+/**
+ * IPC flags and control command defitions
  */
-#define RT_IPC_FLAG_FIFO				0x00			/* FIFOed IPC. @ref IPC. 					*/
-#define RT_IPC_FLAG_PRIO				0x01			/* PRIOed IPC. @ref IPC. 					*/
+#define RT_IPC_FLAG_FIFO				0x00			/**< FIFOed IPC. @ref IPC. 					*/
+#define RT_IPC_FLAG_PRIO				0x01			/**< PRIOed IPC. @ref IPC. 					*/
 
-#define RT_IPC_CMD_UNKNOWN				0x00			/* unknown IPC command 						*/
-#define RT_IPC_CMD_RESET				0x01			/* reset IPC object 						*/
+#define RT_IPC_CMD_UNKNOWN				0x00			/**< unknown IPC command 					*/
+#define RT_IPC_CMD_RESET				0x01			/**< reset IPC object 						*/
 
-#define RT_WAITING_FOREVER				-1				/* Block forever until get resource.		*/
-#define RT_WAITING_NO					0				/* Non-block. 								*/
+#define RT_WAITING_FOREVER				-1				/**< Block forever until get resource.		*/
+#define RT_WAITING_NO					0				/**< Non-block. 							*/
 
-/*
+/**
  * Base structure of IPC object
  */
 struct rt_ipc_object
 {
-	struct rt_object parent;
+	struct rt_object parent;							/**< inherit from rt_object 				*/
 
-	rt_list_t suspend_thread;							/* threads pended on this resource. 		*/
+	rt_list_t suspend_thread;							/**< threads pended on this resource 		*/
 };
 
 #ifdef RT_USING_SEMAPHORE
-/*
- * semaphore
- *
- * Binary and counter semaphore are both supported.
+/**
+ * Semaphore structure
  */
 struct rt_semaphore
 {
-	struct rt_ipc_object parent;
+	struct rt_ipc_object parent;						/**< inherit from ipc_object 				*/
 
-	rt_uint16_t value;									/* value of semaphore. 						*/
+	rt_uint16_t value;									/**< value of semaphore. 					*/
 };
 typedef struct rt_semaphore* rt_sem_t;
 #endif
 
 #ifdef RT_USING_MUTEX
-/*
- * mutex
+/**
+ * Mutual exclusion (mutex) structure
  */
 struct rt_mutex
 {
-	struct rt_ipc_object 	parent;
+	struct rt_ipc_object 	parent;						/**< inherit from ipc_object				*/
 
-	rt_uint16_t 			value;						/* value of mutex. 							*/
+	rt_uint16_t 			value;						/**< value of mutex 						*/
 
-	rt_uint8_t 				original_priority;			/* priority of last thread hold the mutex. 	*/
-	rt_uint8_t 				hold;			 			/* numbers of thread hold the mutex. 		*/
+	rt_uint8_t 				original_priority;			/**< priority of last thread hold the mutex */
+	rt_uint8_t 				hold;			 			/**< numbers of thread hold the mutex 		*/
 
-	struct rt_thread		*owner;						/* current owner of mutex. 					*/
+	struct rt_thread		*owner;						/**< current owner of mutex 				*/
 };
 typedef struct rt_mutex* rt_mutex_t;
 #endif
 
-#if defined(RT_USING_EVENT)
-#define RT_EVENT_FLAG_AND				0x01
-#define RT_EVENT_FLAG_OR				0x02
-#define RT_EVENT_FLAG_CLEAR				0x04
-#endif
-
 #ifdef RT_USING_EVENT
+/**
+ * flag defintions in event
+ */
+#define RT_EVENT_FLAG_AND				0x01			/**< logic and 								*/
+#define RT_EVENT_FLAG_OR				0x02			/**< logic or 								*/
+#define RT_EVENT_FLAG_CLEAR				0x04			/**< clear flag								*/
+
 /*
- * event
+ * event structure
  */
 struct rt_event
 {
-	struct rt_ipc_object parent;
+	struct rt_ipc_object parent;						/**< inherit from ipc_object 				*/
 
-	rt_uint32_t set;									/* event set. 								*/
+	rt_uint32_t set;									/**< event set 								*/
 };
 typedef struct rt_event* rt_event_t;
 #endif
 
 #ifdef RT_USING_MAILBOX
-/*
- * mailbox
+/**
+ * mailbox structure
  *
  */
 struct rt_mailbox
 {
-	struct rt_ipc_object parent;
+	struct rt_ipc_object parent;						/**< inherit from ipc_object 				*/
 
-	rt_uint32_t* msg_pool;							/* start address of message buffer. 			*/
+	rt_uint32_t* msg_pool;								/**< start address of message buffer. 			*/
 
-	rt_uint16_t size;								/* size of message pool. 						*/
+	rt_uint16_t size;									/**< size of message pool. 						*/
 
-	rt_uint16_t entry;								/* index of messages in msg_pool. 				*/
-	rt_uint16_t in_offset, out_offset;				/* in/output offset of the message buffer.		*/
+	rt_uint16_t entry;									/**< index of messages in msg_pool. 				*/
+	rt_uint16_t in_offset, out_offset;					/**< in/output offset of the message buffer.		*/
 };
 typedef struct rt_mailbox* rt_mailbox_t;
 #endif
 
 #ifdef RT_USING_MESSAGEQUEUE
-/*
- * messagequeue
+/**
+ * message queue structure
  */
 struct rt_messagequeue
 {
-	struct rt_ipc_object parent;
+	struct rt_ipc_object parent;						/**< inherit from ipc_object 				*/
 
-	void* msg_pool;									/* start address of message queue. 				*/
+	void* msg_pool;										/**< start address of message queue. 			*/
 
-	rt_uint16_t msg_size;							/* message size of each message. 				*/
-	rt_uint16_t max_msgs;							/* max number of messages. 						*/
+	rt_uint16_t msg_size;								/**< message size of each message. 				*/
+	rt_uint16_t max_msgs;								/**< max number of messages. 					*/
 
-	rt_uint16_t entry;								/* index of messages in the queue. 				*/
+	rt_uint16_t entry;									/**< index of messages in the queue. 			*/
 
-	void* msg_queue_head;							/* list head. 									*/
-	void* msg_queue_tail;							/* list tail. 									*/
-	void* msg_queue_free;							/* pointer indicated the free node of queue. 	*/
+	void* msg_queue_head;								/**< list head. 								*/
+	void* msg_queue_tail;								/**< list tail. 								*/
+	void* msg_queue_free;								/**< pointer indicated the free node of queue. 	*/
 };
 typedef struct rt_messagequeue* rt_mq_t;
 #endif
@@ -500,24 +516,24 @@ typedef struct rt_messagequeue* rt_mq_t;
  * heap & partition
  */
 #ifdef RT_USING_MEMPOOL
-/*
+/**
  * Base structure of Memory pool object
  */
 struct rt_mempool
 {
-	struct rt_object parent;
+	struct rt_object parent;						/**< inherit from rt_object 					*/
 
-	void		*start_address;						/* memory pool start 							*/
-	rt_size_t 	size;								/* size of memory pool 							*/
+	void		*start_address;						/**< memory pool start 							*/
+	rt_size_t 	size;								/**< size of memory pool 						*/
 
-	rt_size_t 	block_size;							/* size of memory blocks 						*/
-	rt_uint8_t	*block_list;						/* memory blocks list 							*/
+	rt_size_t 	block_size;							/**< size of memory blocks 						*/
+	rt_uint8_t	*block_list;						/**< memory blocks list 						*/
 
-	rt_size_t 	block_total_count;					/* numbers of memory block 						*/
-	rt_size_t 	block_free_count;					/* numbers of free memory block 				*/
+	rt_size_t 	block_total_count;					/**< numbers of memory block 					*/
+	rt_size_t 	block_free_count;					/**< numbers of free memory block 				*/
 
-	rt_list_t 	suspend_thread;						/* threads pended on this resource 				*/
-	rt_size_t 	suspend_thread_count;				/* numbers of thread pended on this resource 	*/
+	rt_list_t 	suspend_thread;						/**< threads pended on this resource 			*/
+	rt_size_t 	suspend_thread_count;				/**< numbers of thread pended on this resource 	*/
 };
 typedef struct rt_mempool* rt_mp_t;
 #endif
@@ -529,69 +545,73 @@ typedef struct rt_mempool* rt_mp_t;
  */
 /*@{*/
 
-/*
- * device (I/O) system
+/**
+ * device (I/O) class type
  */
 enum rt_device_class_type
 {
-	RT_Device_Class_Char = 0,						/* character device								*/
-	RT_Device_Class_Block,							/* block device 								*/
-	RT_Device_Class_NetIf,							/* net interface 								*/
-	RT_Device_Class_MTD,							/* memory device 								*/
-	RT_Device_Class_CAN,							/* CAN device 									*/
-	RT_Device_Class_RTC,							/* RTC device 									*/
-	RT_Device_Class_Sound,							/* Sound device 								*/
-	RT_Device_Class_Unknown							/* unknown device 								*/
+	RT_Device_Class_Char = 0,						/**< character device							*/
+	RT_Device_Class_Block,							/**< block device 								*/
+	RT_Device_Class_NetIf,							/**< net interface 								*/
+	RT_Device_Class_MTD,							/**< memory device 								*/
+	RT_Device_Class_CAN,							/**< CAN device 								*/
+	RT_Device_Class_RTC,							/**< RTC device 								*/
+	RT_Device_Class_Sound,							/**< Sound device 								*/
+	RT_Device_Class_Unknown							/**< unknown device 							*/
 };
 
-/* device flags */
-#define RT_DEVICE_FLAG_DEACTIVATE		0x000		/* not inited 									*/
-
-#define RT_DEVICE_FLAG_RDONLY			0x001		/* read only 									*/
-#define RT_DEVICE_FLAG_WRONLY			0x002		/* write only 									*/
-#define RT_DEVICE_FLAG_RDWR				0x003		/* read and write 								*/
-
-#define RT_DEVICE_FLAG_REMOVABLE		0x004		/* removable device 							*/
-#define RT_DEVICE_FLAG_STANDALONE		0x008		/* standalone device							*/
-#define RT_DEVICE_FLAG_ACTIVATED		0x010		/* device is activated 							*/
-#define RT_DEVICE_FLAG_SUSPENDED		0x020		/* device is suspended 							*/
-#define RT_DEVICE_FLAG_STREAM			0x040		/* stream mode 									*/
-
-#define RT_DEVICE_FLAG_INT_RX			0x100		/* INT mode on Rx 								*/
-#define RT_DEVICE_FLAG_DMA_RX			0x200		/* DMA mode on Rx 								*/
-#define RT_DEVICE_FLAG_INT_TX			0x400		/* INT mode on Tx 								*/
-#define RT_DEVICE_FLAG_DMA_TX			0x800		/* DMA mode on Tx								*/
-
-#define RT_DEVICE_OFLAG_CLOSE			0x000		/* device is closed 							*/
-#define RT_DEVICE_OFLAG_RDONLY			0x001		/* read only access								*/
-#define RT_DEVICE_OFLAG_WRONLY			0x002		/* write only access							*/
-#define RT_DEVICE_OFLAG_RDWR			0x003		/* read and write 								*/
-#define RT_DEVICE_OFLAG_OPEN			0x008		/* device is opened 							*/
-
-/* general device commands */
-#define RT_DEVICE_CTRL_RESUME	   		0x01		/* resume device 								*/
-#define RT_DEVICE_CTRL_SUSPEND	    	0x02		/* suspend device 								*/
-
-/* special device commands */
-#define RT_DEVICE_CTRL_CHAR_STREAM		0x10		/* stream mode on char device 					*/
-#define RT_DEVICE_CTRL_BLK_GETGEOME		0x10		/* get geometry information 					*/
-#define RT_DEVICE_CTRL_NETIF_GETMAC		0x10		/* get mac address 								*/
-#define RT_DEVICE_CTRL_MTD_FORMAT		0x10		/* format a MTD device 							*/
-#define RT_DEVICE_CTRL_RTC_GET_TIME		0x10		/* get time 									*/
-#define RT_DEVICE_CTRL_RTC_SET_TIME		0x11		/* set time 									*/
+/**
+ * device flags defitions
+ */
+#define RT_DEVICE_FLAG_DEACTIVATE		0x000		/**< device is not not initialized 				*/
+
+#define RT_DEVICE_FLAG_RDONLY			0x001		/**< read only 									*/
+#define RT_DEVICE_FLAG_WRONLY			0x002		/**< write only 								*/
+#define RT_DEVICE_FLAG_RDWR				0x003		/**< read and write 							*/
+
+#define RT_DEVICE_FLAG_REMOVABLE		0x004		/**< removable device 							*/
+#define RT_DEVICE_FLAG_STANDALONE		0x008		/**< standalone device							*/
+#define RT_DEVICE_FLAG_ACTIVATED		0x010		/**< device is activated 						*/
+#define RT_DEVICE_FLAG_SUSPENDED		0x020		/**< device is suspended 						*/
+#define RT_DEVICE_FLAG_STREAM			0x040		/**< stream mode 								*/
+
+#define RT_DEVICE_FLAG_INT_RX			0x100		/**< INT mode on Rx 							*/
+#define RT_DEVICE_FLAG_DMA_RX			0x200		/**< DMA mode on Rx 							*/
+#define RT_DEVICE_FLAG_INT_TX			0x400		/**< INT mode on Tx 							*/
+#define RT_DEVICE_FLAG_DMA_TX			0x800		/**< DMA mode on Tx								*/
+
+#define RT_DEVICE_OFLAG_CLOSE			0x000		/**< device is closed 							*/
+#define RT_DEVICE_OFLAG_RDONLY			0x001		/**< read only access							*/
+#define RT_DEVICE_OFLAG_WRONLY			0x002		/**< write only access							*/
+#define RT_DEVICE_OFLAG_RDWR			0x003		/**< read and write 							*/
+#define RT_DEVICE_OFLAG_OPEN			0x008		/**< device is opened 							*/
+
+/**
+ * general device commands
+ */
+#define RT_DEVICE_CTRL_RESUME	   		0x01		/**< resume device 								*/
+#define RT_DEVICE_CTRL_SUSPEND	    	0x02		/**< suspend device 							*/
+
+/**
+ * special device commands
+ */
+#define RT_DEVICE_CTRL_CHAR_STREAM		0x10		/**< stream mode on char device 				*/
+#define RT_DEVICE_CTRL_BLK_GETGEOME		0x10		/**< get geometry information 					*/
+#define RT_DEVICE_CTRL_NETIF_GETMAC		0x10		/**< get mac address 							*/
+#define RT_DEVICE_CTRL_MTD_FORMAT		0x10		/**< format a MTD device 						*/
+#define RT_DEVICE_CTRL_RTC_GET_TIME		0x10		/**< get time 									*/
+#define RT_DEVICE_CTRL_RTC_SET_TIME		0x11		/**< set time 									*/
 
 typedef struct rt_device* rt_device_t;
-/*
- * Device related structure
+/**
+ * Device structure
  */
 struct rt_device
 {
-	struct rt_object parent;
+	struct rt_object parent;						/**< inherit from rt_object 					*/
 
-	/* device type */
-	enum rt_device_class_type type;
-	/* device flag and device open flag*/
-	rt_uint16_t flag, open_flag;
+	enum rt_device_class_type type;					/**< device type 								*/
+	rt_uint16_t flag, open_flag;					/**< device flag and device open flag			*/
 
 	/* device call back */
 	rt_err_t (*rx_indicate)(rt_device_t dev, rt_size_t size);
@@ -610,50 +630,57 @@ struct rt_device
 	rt_err_t (*resumed) (rt_device_t dev);
 #endif
 
-	/* device private data */
-	void* private;
+	void* user_data;								/**< device private data 						*/
 };
 
+/**
+ * block device geometry structure
+ */
 struct rt_device_blk_geometry
 {
-	rt_uint32_t sector_count;		/* count of sectors */
-	rt_uint32_t bytes_per_sector;	/* number of bytes per sector */
-	rt_uint32_t block_size;			/* size to erase one block */
+	rt_uint32_t sector_count;						/**< count of sectors							*/
+	rt_uint32_t bytes_per_sector;					/**< number of bytes per sector 				*/
+	rt_uint32_t block_size;							/**< size to erase one block 					*/
 };
+/*@}*/
 
+/**
+ * @addtogroup Module
+ */
+/*@{*/
 #ifdef RT_USING_MODULE
 /*
  * module system
  */
 
 #define RT_MODULE_FLAG_WITHENTRY		0x00		/* with entry point								*/
-#define RT_MODULE_FLAG_WITHOUTENTRY		0x01		/* without entry point								*/
+#define RT_MODULE_FLAG_WITHOUTENTRY		0x01		/* without entry point							*/
 
+/**
+ * Application Module structure
+ */
 struct rt_module
 {
-	/* inherit from object */
-	struct	rt_object parent;
+	struct	rt_object parent;						/**< inherit from object */
 
-	rt_uint8_t* module_space;							/* module memory space						*/
+	rt_uint8_t* module_space;						/**< module memory space						*/
 
-	void*		module_entry;							/* entry address of module's thread			*/
-	rt_thread_t module_thread;							/* stack size of module's thread			*/
-	rt_uint32_t stack_size;								/* priority of module's thread				*/
+	void*		module_entry;						/**< entry address of module's thread			*/
+	rt_thread_t module_thread;						/**< stack size of module's thread				*/
+	rt_uint32_t stack_size;							/**< priority of module's thread				*/
 	rt_uint32_t thread_priority;
 
 	/* module memory allocator */
-	void*		mem_list;								/* module's free memory list				*/
-	rt_list_t	page_list;								/* module's using page list	 				*/
-	rt_mp_t	mpool;															
+	void*		mem_list;							/**< module's free memory list					*/
+	rt_list_t	page_list;							/**< module's using page list	 				*/
+	rt_mp_t	mpool;									/**< module's memory pool 						*/
 
-	/* module symbol table */
-	rt_uint32_t nsym;
-	struct rt_module_symtab *symtab;
+	rt_uint32_t nsym;								/**< number of symbol in the module 			*/
+	struct rt_module_symtab *symtab;				/**< module symbol table 						*/
 
-	/* reference count */
-	rt_uint32_t nref;		
+	rt_uint32_t nref;								/**< reference count 							*/
 	
-	/* object in this module, module object is the last basic object type */
+	/**< object in this module, module object is the last basic object type */
 	struct rt_object_information module_object[RT_Object_Class_Unknown];
 };
 typedef struct rt_module* rt_module_t;

include/rtthread.h

@@ -318,6 +318,7 @@ rt_module_t rt_module_self (void);
 rt_err_t rt_module_set (rt_module_t module);
 rt_module_t rt_module_find(const char* name);
 #endif
+/*@}*/
  
 /*
  * interrupt service

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);

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);
 }
-
-/*@}*/

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)
 {

src/kservice.h

@@ -23,6 +23,11 @@
 extern "C" {
 #endif
 
+/**
+ * @addtogroup KernelService
+ */
+/*@{*/
+
 /**
  * @brief initialize a list
  *
@@ -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

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);

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)

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;

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)
 {

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

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)
 {

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);