update doxygen comments.

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

8 files changed, 153 insertions, 60 deletions

diff --git a/components/dfs/src/dfs.c b/components/dfs/src/dfs.c
index 7d0d061b9a..d1ecda80eb 100644
--- a/components/dfs/src/dfs.c
+++ b/components/dfs/src/dfs.c
@@ -36,6 +36,11 @@ struct dfs_fd fd_table[DFS_FD_MAX];
 #endif

 

 /**

+ * @addtogroup DFS

+ */

+/*@{*/

+

+/**

  * this function will initialize device file system.

  */

 void dfs_init()

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

 }

+/*@}*/

+

diff --git a/components/dfs/src/dfs_file.c b/components/dfs/src/dfs_file.c
index 88a9feacf8..95c9e9462a 100644
--- a/components/dfs/src/dfs_file.c
+++ b/components/dfs/src/dfs_file.c
@@ -17,6 +17,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.

  *

  * @param fd the file descriptor pointer to return the corresponding result.

@@ -530,3 +535,5 @@ void cat(const char* filename)
 FINSH_FUNCTION_EXPORT(cat, print file)

 

 #endif

+/* @} */

+

diff --git a/components/dfs/src/dfs_fs.c b/components/dfs/src/dfs_fs.c
index 9db83a16c9..f6e7867578 100644
--- a/components/dfs/src/dfs_fs.c
+++ b/components/dfs/src/dfs_fs.c
@@ -16,6 +16,11 @@
 #include <dfs_file.h>

 

 /**

+ * @addtogroup FsApi

+ */

+/*@{*/

+

+/**

  * this function will register a file system instance to device file system.

  *

  * @param ops the file system instance to be registered.

@@ -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

 

+/* @} */

diff --git a/components/dfs/src/dfs_posix.c b/components/dfs/src/dfs_posix.c
index 6a3517e89d..436230d849 100644
--- a/components/dfs/src/dfs_posix.c
+++ b/components/dfs/src/dfs_posix.c
@@ -16,6 +16,11 @@
 #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;

 }

 

+/* @} */

diff --git a/components/finsh/finsh.h b/components/finsh/finsh.h
index 1faa38b8be..87f8d72780 100644
--- a/components/finsh/finsh.h
+++ b/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
diff --git a/components/finsh/shell.c b/components/finsh/shell.c
index 17ee92be5a..d78461b532 100644
--- a/components/finsh/shell.c
+++ b/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;
diff --git a/components/finsh/shell.h b/components/finsh/shell.h
index bf027c3561..d810a71c0b 100644
--- a/components/finsh/shell.h
+++ b/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

diff --git a/components/libc/newlib/libc.c b/components/libc/newlib/libc.c
index 7d2c3cac56..de8523a1f6 100644
--- a/components/libc/newlib/libc.c
+++ b/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);