[rtems commit] libfs: Doxygen Clean Up Task #2
Jennifer Averett
jennifer at rtems.org
Fri Jan 4 14:36:48 UTC 2013
Module: rtems
Branch: master
Commit: 2305f9711772ba1a139c05adb9d488ed91e8eb30
Changeset: http://git.rtems.org/rtems/commit/?id=2305f9711772ba1a139c05adb9d488ed91e8eb30
Author: Mathew Kallada <matkallada at gmail.com>
Date: Fri Jan 4 08:39:30 2013 -0600
libfs: Doxygen Clean Up Task #2
There were minor conflicts and the modifications that were
in the repo were favored over the modifications in the submitted
patch.
---
cpukit/libfs/src/dosfs/dosfs.h | 6 +-
cpukit/libfs/src/dosfs/fat.h | 25 ++++++--
cpukit/libfs/src/dosfs/fat_fat_operations.h | 15 +++-
cpukit/libfs/src/dosfs/fat_file.h | 43 +++++++-----
cpukit/libfs/src/dosfs/msdos.h | 15 +++--
cpukit/libfs/src/nfsclient/proto/mount_prot.h | 9 ++-
cpukit/libfs/src/nfsclient/src/librtemsNfs.h | 85 ++++++++++++++++---------
cpukit/libfs/src/nfsclient/src/rpcio.h | 49 +++++++++++----
cpukit/libfs/src/rfs/rtems-rfs-group.h | 42 +++++++++----
9 files changed, 195 insertions(+), 94 deletions(-)
diff --git a/cpukit/libfs/src/dosfs/dosfs.h b/cpukit/libfs/src/dosfs/dosfs.h
index 2374e63..79560bb 100644
--- a/cpukit/libfs/src/dosfs/dosfs.h
+++ b/cpukit/libfs/src/dosfs/dosfs.h
@@ -1,7 +1,9 @@
/**
- * @file rtems/dosfs.h
+ * @file rtems/dosfs.h
*
- * Application interface to MSDOS filesystem.
+ * @brief Application Interface to MSDOS Filesystem
+ *
+ * @ingroup rtems_msdos_format
*/
/*
diff --git a/cpukit/libfs/src/dosfs/fat.h b/cpukit/libfs/src/dosfs/fat.h
index 5d36fb4..ace236b 100644
--- a/cpukit/libfs/src/dosfs/fat.h
+++ b/cpukit/libfs/src/dosfs/fat.h
@@ -1,8 +1,15 @@
-/*
- * fat.h
+/**
+ * @file
+ *
+ * @brief Constants/Data Structures/Prototypes on a Volume with FAT Filesystem
*
- * Constants/data structures/prototypes for low-level operations on a volume
- * with FAT filesystem
+ * @ingroup libfs_dosfs
+ *
+ * Constants/Data Structures/Prototypes for Low-Level
+ * Operations on a Volume with FAT Filesystem
+ */
+
+/*
*
* Copyright (C) 2001 OKTET Ltd., St.-Petersburg, Russia
* Author: Eugeny S. Mints <Eugeny.Mints at oktet.ru>
@@ -23,6 +30,12 @@
#include <errno.h>
#include <rtems/bdbuf.h>
+/**
+ * @defgroup libfs_dosfs FAT FileSystem
+ *
+ * @ingroup libfs
+ */
+/**@{*/
#ifdef __cplusplus
extern "C" {
#endif
@@ -545,5 +558,5 @@ fat_sync(fat_fs_info_t *fs_info);
#ifdef __cplusplus
}
#endif
-
-#endif /* __DOSFS_FAT_H__ */
+/**@}*/
+#endif /* __DOSFS_FAT_H__ */
\ No newline at end of file
diff --git a/cpukit/libfs/src/dosfs/fat_fat_operations.h b/cpukit/libfs/src/dosfs/fat_fat_operations.h
index 278947f..6958915 100644
--- a/cpukit/libfs/src/dosfs/fat_fat_operations.h
+++ b/cpukit/libfs/src/dosfs/fat_fat_operations.h
@@ -1,9 +1,15 @@
-/*
- * fat_fat_operations.h
+/**
+ * @file
*
- * Constants/data structures/prototypes for operations on Files Allocation
- * Table
+ * @brief Constants/Data Structures/Prototypes for Files Allocation Table
*
+ * @ingroup libfs_ffo
+ *
+ * Constants/Data Structures/Prototypes for
+ * Operations on Files Allocation Table
+ */
+
+/*
* Copyright (C) 2001 OKTET Ltd., St.-Petersburg, Russia
* Author: Eugeny S. Mints <Eugeny.Mints at oktet.ru>
*
@@ -11,6 +17,7 @@
* found in the file LICENSE in this distribution or at
* http://www.rtems.com/license/LICENSE.
*/
+
#ifndef __DOSFS_FAT_FAT_OPERATIONS_H__
#define __DOSFS_FAT_FAT_OPERATIONS_H__
diff --git a/cpukit/libfs/src/dosfs/fat_file.h b/cpukit/libfs/src/dosfs/fat_file.h
index 0e22c90..d9753a9 100644
--- a/cpukit/libfs/src/dosfs/fat_file.h
+++ b/cpukit/libfs/src/dosfs/fat_file.h
@@ -1,7 +1,12 @@
-/*
- * fat_file.h
+/**
+ * @file
*
- * Constants/data structures/prototypes for operations on "fat-file"
+ * @brief Constants/Data Structures/Prototypes for Operations on "fat-file"
+ *
+ * @ingroup libfs_ff
+ */
+
+/*
*
* Copyright (C) 2001 OKTET Ltd., St.-Petersburg, Russia
* Author: Eugeny S. Mints <Eugeny.Mints at oktet.ru>
@@ -10,6 +15,7 @@
* found in the file LICENSE in this distribution or at
* http://www.rtems.com/license/LICENSE.
*/
+
#ifndef __DOSFS_FAT_FILE_H__
#define __DOSFS_FAT_FILE_H__
@@ -26,11 +32,13 @@
* @ingroup libfs
*/
/**@{*/
+
#ifdef __cplusplus
extern "C" {
#endif
-/* "fat-file" representation
+/**
+ * @brief The "fat-file" representation.
*
* the idea is: fat-file is nothing but a cluster chain, any open fat-file is
* represented in system by fat-file descriptor and has well-known
@@ -44,7 +52,6 @@ extern "C" {
* Such interface hides the architecture of fat-file and represents it like
* linear file
*/
-
typedef rtems_filesystem_node_types_t fat_file_type_t;
#define FAT_DIRECTORY RTEMS_FILESYSTEM_DIRECTORY
@@ -56,8 +63,9 @@ typedef struct fat_file_map_s
uint32_t disk_cln;
uint32_t last_cln;
} fat_file_map_t;
-/*
- * descriptor of a fat-file
+
+/**
+ * @brief Descriptor of a fat-file.
*
* To each particular clusters chain
*/
@@ -109,18 +117,17 @@ typedef struct fat_file_fd_s
#define FAT_EOF 0x00
-/* fat_construct_key --
- * Construct key for hash access: convert (cluster num, offset) to
- * (sector512 num, new offset) and than construct key as
- * key = (sector512 num) << 4 | (new offset)
+/* @brief Construct key for hash access.
+ *
+ * Construct key for hash access: convert (cluster num, offset) to
+ * (sector512 num, new offset) and than construct key as
+ * key = (sector512 num) << 4 | (new offset)
*
- * PARAMETERS:
- * cl - cluster number
- * ofs - offset inside cluster 'cl'
- * fs_info - FS info
+ * @param[in] cl - cluster number
+ * @param[in] ofs - offset inside cluster 'cl'
+ * @param[in] fs_info - FS info
*
- * RETURNS:
- * constructed key
+ * @retval constructed key
*/
static inline uint32_t
fat_construct_key(
@@ -189,4 +196,4 @@ fat_file_mark_removed(fat_fs_info_t *fs_info,
}
#endif
/**@}*/
-#endif /* __DOSFS_FAT_FILE_H__ */
+#endif /* __DOSFS_FAT_FILE_H__ */
\ No newline at end of file
diff --git a/cpukit/libfs/src/dosfs/msdos.h b/cpukit/libfs/src/dosfs/msdos.h
index d4f6743..9465d26 100644
--- a/cpukit/libfs/src/dosfs/msdos.h
+++ b/cpukit/libfs/src/dosfs/msdos.h
@@ -1,8 +1,12 @@
-/*
- * msdos.h
+/**
+ * @file
*
- * The MSDOS filesystem constants/data structures/prototypes
+ * @brief The MSDOS Filesystem Constants/Data Structures/Prototypes
*
+ * @ingroup libfs_msdos
+ */
+
+/*
* Copyright (C) 2001 OKTET Ltd., St.-Petersburg, Russia
* Author: Eugeny S. Mints <Eugeny.Mints at oktet.ru>
*
@@ -10,6 +14,7 @@
* found in the file LICENSE in this distribution or at
* http://www.rtems.com/license/LICENSE.
*/
+
#ifndef __DOSFS_MSDOS_H__
#define __DOSFS_MSDOS_H__
@@ -276,7 +281,7 @@ int msdos_rmnod(
);
/**
- * @brief rename a MSDOS filesystem node
+ * @brief Rename a MSDOS filesystem node.
*
* Routine to rename a MSDOS filesystem node
*/
@@ -293,7 +298,7 @@ void msdos_lock(const rtems_filesystem_mount_table_entry_t *mt_entry);
void msdos_unlock(const rtems_filesystem_mount_table_entry_t *mt_entry);
/**
- * @brief The MSDOS filesystem initialization.
+ * @brief MSDOS filesystem initialization routine.
*
* MSDOS Initialization support routine implementation
*/
diff --git a/cpukit/libfs/src/nfsclient/proto/mount_prot.h b/cpukit/libfs/src/nfsclient/proto/mount_prot.h
index e74a3cd..a5cac29 100644
--- a/cpukit/libfs/src/nfsclient/proto/mount_prot.h
+++ b/cpukit/libfs/src/nfsclient/proto/mount_prot.h
@@ -1,6 +1,9 @@
-/*
- * Please do not edit this file.
- * It was generated using rpcgen.
+/**
+ * @file
+ *
+ * @brief Nfsclient Mount Prot
+ *
+ * @ingroup rtems-nfsclient
*/
#ifndef _MOUNT_PROT_H_RPCGEN
diff --git a/cpukit/libfs/src/nfsclient/src/librtemsNfs.h b/cpukit/libfs/src/nfsclient/src/librtemsNfs.h
index fc48028..ddef9ee 100644
--- a/cpukit/libfs/src/nfsclient/src/librtemsNfs.h
+++ b/cpukit/libfs/src/nfsclient/src/librtemsNfs.h
@@ -1,11 +1,14 @@
-#ifndef LIB_RTEMS_NFS_CLIENT_H
-#define LIB_RTEMS_NFS_CLIENT_H
-
-/* public interface to the NFS client library for RTEMS */
-
-/* Author: Till Straumann <strauman at slac.stanford.edu> 2002-2003 */
+/**
+ * @file
+ *
+ * @brief Public Interface to the NFS Client Library for RTEMS
+ *
+ * @ingroup rtems-nfsclient
+ */
/*
+ * Author: Till Straumann <strauman at slac.stanford.edu> 2002-2003
+ *
* Authorship
* ----------
* This software (NFS-2 client implementation for RTEMS) was created by
@@ -50,6 +53,16 @@
* ------------------ SLAC Software Notices, Set 4 OTT.002a, 2004 FEB 03
*/
+#ifndef LIB_RTEMS_NFS_CLIENT_H
+#define LIB_RTEMS_NFS_CLIENT_H
+
+/**
+ * @defgroup rtems-nfsclient NFS Client Library
+ *
+ * @ingroup nfsclient
+ * @{
+ */
+
#ifdef HAVE_CONFIG_H
#include <config.h>
#endif
@@ -73,40 +86,41 @@
extern "C" {
#endif
-/* RPCIO driver interface.
+/** RPCIO driver interface.
* If you need RPCIO for other purposes than NFS
* you may want to include <rpcio.h>
#include "rpcio.h"
*/
-/* Priority of daemon; may be setup prior to calling rpcUdpInit();
+/** Priority of daemon; may be setup prior to calling rpcUdpInit();
* otherwise the network task priority from the rtems_bsdnet_config
* is used...
*/
extern rtems_task_priority rpciodPriority;
-/* Initialize the driver.
+/** Initialize the driver.
*
* Note, called in nfsfs initialise when mount is called.
*
- * RETURNS: 0 on success, -1 on failure
+ * @retval 0 on success, -1 on failure
*/
int
rpcUdpInit(void);
-/* Cleanup/Stop
+/**
+ * @brief RPC cleanup and stop.
*
- * RETURNS: 0 on success, nonzero if still in use
+ * @retval 0 on success, nonzero if still in use
*/
int
rpcUdpCleanup(void);
-/* NFS driver interface */
+/** NFS driver interface */
-/* Initialize the NFS driver.
+/**
+ * @brief Initialize the NFS driver.
*
- * NOTE: The RPCIO driver must have been initialized prior to
- * calling this.
+ * The RPCIO driver must have been initialized prior to calling this.
*
* Note, called in nfsfs initialise when mount is called with defaults.
*
@@ -125,50 +139,60 @@ rpcUdpCleanup(void);
void
nfsInit(int smallPoolDepth, int bigPoolDepth);
-/* Driver cleanup code
+/**
+ * @brief Driver cleanup code.
*
- * RETURNS: 0 on success, nonzero if still in use
+ * @retval 0 on success, nonzero if still in use
*/
int
nfsCleanup(void);
-/* Dump a list of the currently mounted NFS to a file
+/**
+ * @brief Dump a list of the currently mounted NFS to a file.
+ *
+ * Dump a list of the currently mounted NFS to a file
* (stdout is used in case f==NULL)
*/
int
nfsMountsShow(FILE *f);
-/*
+/**
+ * @brief Filesystem mount table mount handler.
+ *
* Filesystem mount table mount handler. Do not call, use the mount call.
*/
-int
+int
rtems_nfs_initialize(rtems_filesystem_mount_table_entry_t *mt_entry,
const void *data);
-/* A utility routine to find the path leading to a
+/**
+ * @brief A utility routine to find the path leading to a
* rtems_filesystem_location_info_t node.
*
* This should really be present in libcsupport...
*
- * INPUT: 'loc' and a buffer 'buf' (length 'len') to hold the
- * path.
- * OUTPUT: path copied into 'buf'
+ * @param[in] 'loc' and a buffer 'buf' (length 'len') to hold the path.
+ *
+ * @param[out] path copied into 'buf'
*
- * RETURNS: 0 on success, RTEMS error code on error.
+ * @retval 0 on success, RTEMS error code on error.
*/
rtems_status_code
rtems_filesystem_resolve_location(char *buf, int len, rtems_filesystem_location_info_t *loc);
-/* Set the timeout (initial default: 10s) for NFS and mount calls.
+/**
+ * @brief Set the timeout (initial default: 10s) for NFS and mount calls.
*
- * RETURNS 0 on success, nonzero if the requested timeout is less than
+ * Set the timeout (initial default: 10s) for NFS and mount calls.
+ *
+ * @retval 0 on success, nonzero if the requested timeout is less than
* a clock tick or if the system clock rate cannot be determined.
*/
int
nfsSetTimeout(uint32_t timeout_ms);
-/* Read current timeout (in milliseconds) */
+/** Read current timeout (in milliseconds) */
uint32_t
nfsGetTimeout(void);
@@ -176,4 +200,5 @@ nfsGetTimeout(void);
}
#endif
-#endif
+/** @} */
+#endif
\ No newline at end of file
diff --git a/cpukit/libfs/src/nfsclient/src/rpcio.h b/cpukit/libfs/src/nfsclient/src/rpcio.h
index 8078209..02cd34f 100644
--- a/cpukit/libfs/src/nfsclient/src/rpcio.h
+++ b/cpukit/libfs/src/nfsclient/src/rpcio.h
@@ -1,11 +1,14 @@
-#ifndef RPCIO_H
-#define RPCIO_H
-
-/* A multihreaded RPC/UDP multiplexor */
-
-/* Author: Till Straumann, <strauman at slac.stanford.edu>, 2002 */
+/**
+ * @file
+ *
+ * @brief A Multithreaded RPC/UDP Multiplexor
+ *
+ * @ingroup rtems-nfsclient
+ */
/*
+ * Author: Till Straumann, <strauman at slac.stanford.edu>, 2002
+ *
* Authorship
* ----------
* This software (NFS-2 client implementation for RTEMS) was created by
@@ -50,6 +53,16 @@
* ------------------ SLAC Software Notices, Set 4 OTT.002a, 2004 FEB 03
*/
+#ifndef RPCIO_H
+#define RPCIO_H
+
+/**
+ * @defgroup rtems-nfsclient RPC/UDP Multiplexor
+ *
+ * @ingroup nfsclient
+ * @{
+ */
+
#ifdef __rtems
#include <rtems.h>
#endif
@@ -84,8 +97,9 @@ rpcUdpServerCreate(
void
rpcUdpServerDestroy(RpcUdpServer s);
-/* Dump statistics to a file (stdout if NULL);
- * returns 0 for convenience
+/**
+ * @brief Dump statistics to a file (stdout if NULL);
+ * @retval 0 for convenience
*/
int
rpcUdpStats(FILE *f);
@@ -103,7 +117,9 @@ rpcUdpClntCreate(
void
RpcUdpClntDestroy(RpcUdpClnt clnt);
-/* mute compiler warnings */
+/**
+ * @brief Mute compiler warnings.
+ */
typedef void *XdrProcT;
typedef void *CaddrT;
@@ -130,7 +146,9 @@ rpcUdpXactDestroy(
RpcUdpXact xact
);
-/* send a transaction */
+/**
+ * Send a transaction.
+ */
enum clnt_stat
rpcUdpSend(
RpcUdpXact xact,
@@ -144,7 +162,9 @@ rpcUdpSend(
... /* 0 terminated xdrproc/pobj additional argument list */
);
-/* wait for a transaction to complete */
+/**
+ * @brief Wait for a transaction to complete.
+ */
enum clnt_stat
rpcUdpRcv(RpcUdpXact xact);
@@ -165,9 +185,11 @@ rpcUdpCallRp(
);
-/* manage pools of transactions */
-/* A pool of transactions. The idea is not to malloc/free them
+/*
+ * @brief Manage pools of transactions.
+ *
+ * A pool of transactions. The idea is not to malloc/free them
* all the time but keep a limited number around in a 'pool'.
* Users who need a XACT may get it from the pool and put it back
* when done.
@@ -205,4 +227,5 @@ rpcUdpXactPoolGet(RpcUdpXactPool pool, XactPoolGetMode mode);
void
rpcUdpXactPoolPut(RpcUdpXact xact);
+/** @} */
#endif
diff --git a/cpukit/libfs/src/rfs/rtems-rfs-group.h b/cpukit/libfs/src/rfs/rtems-rfs-group.h
index 257eb49..90c6a9a 100644
--- a/cpukit/libfs/src/rfs/rtems-rfs-group.h
+++ b/cpukit/libfs/src/rfs/rtems-rfs-group.h
@@ -22,6 +22,13 @@
#if !defined (_RTEMS_RFS_GROUP_H_)
#define _RTEMS_RFS_GROUP_H_
+/**
+ * @defgroup rtems-rfs FS Group Management
+ *
+ * @ingroup rfs
+ * @{
+ */
+
#include <rtems/rfs/rtems-rfs-trace.h>
#include <rtems/rfs/rtems-rfs-bitmaps.h>
#include <rtems/rfs/rtems-rfs-buffer.h>
@@ -34,6 +41,8 @@
#define RTEMS_RFS_GROUP_INODE_BLOCK (2)
/**
+ * @brief Creates bit allocator for blocks in the group simpler.
+ *
* A group is a selection of blocks on the disk. Typically the number of blocks
* in a group is determined by the number of bits a block holds. This makes the
* bit allocator for blocks in the group simpler plus is allows a simple way to
@@ -85,13 +94,15 @@ typedef struct _rtems_rfs_group
(((_f)->group_inodes * (_g)) + (_i) + RTEMS_RFS_ROOT_INO)
/**
- * Open a group. Allocate all the resources including the bitmaps.
+ * @brief Open a group.
+ *
+ * Allocate all the resources including the bitmaps.
*
* @param fs The file system.
* @param base The base block number.
* @param size The number of blocks in the group.
* @param group Reference to the group to open.
- * @return int The error number (errno). No error if 0.
+ * @retval int The error number (errno). No error if 0.
*/
int rtems_rfs_group_open (rtems_rfs_file_system* fs,
rtems_rfs_buffer_block base,
@@ -100,24 +111,28 @@ int rtems_rfs_group_open (rtems_rfs_file_system* fs,
rtems_rfs_group* group);
/**
- * Close a group. Release all resources the group holds.
+ * @brief Close a group.
+ *
+ * Release all resources the group holds.
*
* @param fs The file system.
* @param group The group to close.
- * @return int The error number (errno). No error if 0.
+ * @retval int The error number (errno). No error if 0.
*/
int rtems_rfs_group_close (rtems_rfs_file_system* fs,
rtems_rfs_group* group);
/**
- * Allocate an inode or block. The groups are searched to find the next
+ * @brief Allocate an inode or block.
+ *
+ * The groups are searched to find the next
* available inode or block.
*
* @param fs The file system data.
* @param goal The goal to seed the bitmap search.
* @param inode If true allocate an inode else allocate a block.
* @param result The allocated bit in the bitmap.
- * @return int The error number (errno). No error if 0.
+ * @retval int The error number (errno). No error if 0.
*/
int rtems_rfs_group_bitmap_alloc (rtems_rfs_file_system* fs,
rtems_rfs_bitmap_bit goal,
@@ -125,25 +140,25 @@ int rtems_rfs_group_bitmap_alloc (rtems_rfs_file_system* fs,
rtems_rfs_bitmap_bit* result);
/**
- * Free the group allocated bit.
+ * @brief Free the group allocated bit.
*
* @param fs The file system data.
* @param inode If true the number to free is an inode else it is a block.
* @param block The inode or block number to free.
- * @return int The error number (errno). No error if 0.
+ * @retval int The error number (errno). No error if 0.
*/
int rtems_rfs_group_bitmap_free (rtems_rfs_file_system* fs,
bool inode,
rtems_rfs_bitmap_bit no);
/**
- * Test the group allocated bit.
+ * @brief Test the group allocated bit.
*
* @param fs The file system data.
* @param inode If true the number to free is an inode else it is a block.
* @param block The inode or block number to free.
* @param state Return the state of the bit.
- * @return int The error number (errno). No error if 0.
+ * @retval int The error number (errno). No error if 0.
*/
int rtems_rfs_group_bitmap_test (rtems_rfs_file_system* fs,
bool inode,
@@ -151,15 +166,16 @@ int rtems_rfs_group_bitmap_test (rtems_rfs_file_system* fs,
bool* state);
/**
- * Determine the number of blocks and inodes used.
+ * @brief Determine the number of blocks and inodes used.
*
* @param fs The file system data.
* @param blocks The number of blocks used.
* @param inodes The number of inodes used.
- * @return int The error number (errno). No error if 0.
+ * @retval int The error number (errno). No error if 0.
*/
int rtems_rfs_group_usage (rtems_rfs_file_system* fs,
size_t* blocks,
size_t* inodes);
-#endif
+/** @} */
+#endif
\ No newline at end of file
More information about the vc
mailing list