From 2305f9711772ba1a139c05adb9d488ed91e8eb30 Mon Sep 17 00:00:00 2001 From: Mathew Kallada Date: Fri, 4 Jan 2013 08:39:30 -0600 Subject: 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 2374e63f2b..79560bb373 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 5d36fb45c0..ace236b50e 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 @@ -23,6 +30,12 @@ #include #include +/** + * @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 278947ffca..69589153d2 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 * @@ -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 0e22c90e60..d9753a9d5b 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 @@ -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 d4f674317f..9465d268d7 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 * @@ -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 e74a3cd688..a5cac29217 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 fc4802874a..ddef9eeab9 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 2002-2003 */ +/** + * @file + * + * @brief Public Interface to the NFS Client Library for RTEMS + * + * @ingroup rtems-nfsclient + */ /* + * Author: Till Straumann 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 #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 #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 8078209610..02cd34ffe7 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, , 2002 */ +/** + * @file + * + * @brief A Multithreaded RPC/UDP Multiplexor + * + * @ingroup rtems-nfsclient + */ /* + * Author: Till Straumann, , 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 #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 257eb49f34..90c6a9aa88 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 #include #include @@ -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 -- cgit v1.2.3