Skip to content

Minor Doxygen fixes for all file system classes #9305

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
Jan 11, 2019
Merged

Minor Doxygen fixes for all file system classes #9305

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
211 changes: 106 additions & 105 deletions features/storage/filesystem/FileSystem.h
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -26,19 +26,19 @@
#include "BlockDevice.h"

namespace mbed {
/** \addtogroup filesystem */
/** \addtogroup file system */
/** @{*/


// Opaque pointer representing files and directories
// Opaque pointer representing files and directories.
typedef void *fs_file_t;
typedef void *fs_dir_t;

// Predeclared classes
// Predeclared classes.
class Dir;
class File;

/** A filesystem object provides filesystem operations and file operations
/** A file system object. Provides file system operations and file operations
* for the File and Dir classes on a block device.
*
* Implementations must provide at minimum file operations and mount
Expand All @@ -49,174 +49,174 @@ class File;
class FileSystem : public FileSystemLike {
public:

/** FileSystem lifetime
/** File system lifetime.
*
* @param name Name to add filesystem to tree as
* @param name Name to add file system to tree as.
*/
FileSystem(const char *name = NULL);
virtual ~FileSystem() {}

/** Return the default filesystem
/** Return the default file system.
*
* Returns the default FileSystem base on the default BlockDevice configuration.
* Returns the default file system based on the default block device configuration.
* Use the components in target.json or application config to change
* the default block device and affect the default filesystem.
* SD block device => FAT filesystem
* SPIF block device => LITTLE filesystem
* DATAFLASH block device => LITTLE filesystem
* QSPIF, SPIF, DATAFLASH or FLAHIAP block device => LITTLE filesystem
*
* An application can override all target settings by implementing
* FileSystem::get_default_instance() themselves - the default
* FileSystem::get_default_instance() - the default
* definition is weak, and calls get_target_default_instance().
*/
static FileSystem *get_default_instance();

/** Mounts a filesystem to a block device
/** Mount a file system to a block device.
*
* @param bd BlockDevice to mount to
* @return 0 on success, negative error code on failure
* @param bd Block device to mount to.
* @return 0 on success, negative error code on failure.
*/
virtual int mount(BlockDevice *bd) = 0;

/** Unmounts a filesystem from the underlying block device
/** Unmount a file system from the underlying block device.
*
* @return 0 on success, negative error code on failure
* @return 0 on success, negative error code on failure.
*/
virtual int unmount() = 0;

/** Reformats a filesystem, results in an empty and mounted filesystem
/** Reformat a file system. Results in an empty and mounted file system.
*
* @param bd BlockDevice to reformat and mount. If NULL, the mounted
* block device will be used.
* Note: if mount fails, bd must be provided.
* @param bd Block device to reformat and mount. If NULL, the mounted
* Block device is used.
* Note: If mount fails, bd must be provided.
* Default: NULL
* @return 0 on success, negative error code on failure
* @return 0 on success, negative error code on failure.
*/
virtual int reformat(BlockDevice *bd = NULL);

/** Remove a file from the filesystem.
/** Remove a file from the file system.
*
* @param path The name of the file to remove.
* @return 0 on success, negative error code on failure
* @return 0 on success, negative error code on failure.
*/
virtual int remove(const char *path);

/** Rename a file in the filesystem.
/** Rename a file in the file system.
*
* @param path The name of the file to rename.
* @param newpath The name to rename it to
* @return 0 on success, negative error code on failure
* @param path The existing name of the file to rename.
* @param newpath The new name of the file.
* @return 0 on success, negative error code on failure.
*/
virtual int rename(const char *path, const char *newpath);

/** Store information about the file in a stat structure
/** Store information about the file in a stat structure.
*
* @param path The name of the file to find information about
* @param st The stat buffer to write to
* @return 0 on success, negative error code on failure
* @param path The name of the file to find information about.
* @param st The stat buffer to write to.
* @return 0 on success, negative error code on failure.
*/
virtual int stat(const char *path, struct stat *st);

/** Create a directory in the filesystem.
/** Create a directory in the file system.
*
* @param path The name of the directory to create.
* @param mode The permissions with which to create the directory
* @return 0 on success, negative error code on failure
* @param mode The permissions with which to create the directory.
* @return 0 on success, negative error code on failure.
*/
virtual int mkdir(const char *path, mode_t mode);

/** Store information about the mounted filesystem in a statvfs structure
/** Store information about the mounted file system in a statvfs structure.
*
* @param path The name of the file to find information about
* @param buf The stat buffer to write to
* @return 0 on success, negative error code on failure
* @param path The name of the file to find information about.
* @param buf The stat buffer to write to.
* @return 0 on success, negative error code on failure.
*/
virtual int statvfs(const char *path, struct statvfs *buf);

protected:
friend class File;
friend class Dir;

/** Open a file on the filesystem
#if !(DOXYGEN_ONLY)
/** Open a file on the file system.
*
* @param file Destination for the handle to a newly created file
* @param path The name of the file to open
* @param flags The flags to open the file in, one of O_RDONLY, O_WRONLY, O_RDWR,
* bitwise or'd with one of O_CREAT, O_TRUNC, O_APPEND
* @return 0 on success, negative error code on failure
* @param file Destination of the newly created handle to the referenced file.
* @param path The name of the file to open.
* @param flags The flags that trigger opening of the file. These flags are O_RDONLY, O_WRONLY, and O_RDWR,
* with an O_CREAT, O_TRUNC, or O_APPEND bitwise OR operator.
* @return 0 on success, negative error code on failure.
*/
virtual int file_open(fs_file_t *file, const char *path, int flags) = 0;

/** Close a file
/** Close a file.
*
* @param file File handle
* @return 0 on success, negative error code on failure
* @param file File handle.
* return 0 on success, negative error code on failure.
*/
virtual int file_close(fs_file_t file) = 0;

/** Read the contents of a file into a buffer
/** Read the contents of a file into a buffer.
*
* @param file File handle
* @param buffer The buffer to read in to
* @param size The number of bytes to read
* @return The number of bytes read, 0 at end of file, negative error on failure
* @param file File handle.
* @param buffer The buffer to read in to.
* @param size The number of bytes to read.
* @return The number of bytes read, 0 at the end of the file, negative error on failure.
*/
virtual ssize_t file_read(fs_file_t file, void *buffer, size_t size) = 0;

/** Write the contents of a buffer to a file
/** Write the contents of a buffer to a file.
*
* @param file File handle
* @param buffer The buffer to write from
* @param size The number of bytes to write
* @return The number of bytes written, negative error on failure
* @param file File handle.
* @param buffer The buffer to write from.
* @param size The number of bytes to write.
* @return The number of bytes written, negative error on failure.
*/
virtual ssize_t file_write(fs_file_t file, const void *buffer, size_t size) = 0;

/** Flush any buffers associated with the file
/** Flush any buffers associated with the file.
*
* @param file File handle
* @return 0 on success, negative error code on failure
* @param file File handle.
* @return 0 on success, negative error code on failure.
*/
virtual int file_sync(fs_file_t file);

/** Check if the file in an interactive terminal device
* If so, line buffered behaviour is used by default
/** Check whether the file is an interactive terminal device.
* If so, line buffered behavior is used by default.
*
* @param file File handle
* @return True if the file is a terminal
* @param file File handle.
* @return True if the file is a terminal.
*/
virtual int file_isatty(fs_file_t file);

/** Move the file position to a given offset from from a given location
/** Move the file position to a given offset from a given location.
*
* @param file File handle
* @param offset The offset from whence to move to
* @param whence The start of where to seek
* SEEK_SET to start from beginning of file,
* SEEK_CUR to start from current position in file,
* SEEK_END to start from end of file
* @param file File handle.
* @param offset The offset from whence to move to.
* @param whence The start of where to seek.
* SEEK_SET to start from the beginning of the file,
* SEEK_CUR to start from the current position in the file,
* SEEK_END to start from the end of the file.
* @return The new offset of the file
*/
virtual off_t file_seek(fs_file_t file, off_t offset, int whence) = 0;

/** Get the file position of the file
/** Get the file position of the file.
*
* @param file File handle
* @return The current offset in the file
* @param file File handle.
* @return The current offset in the file.
*/
virtual off_t file_tell(fs_file_t file);

/** Rewind the file position to the beginning of the file
/** Rewind the file position to the beginning of the file.
*
* @param file File handle
* @param file File handle.
* @note This is equivalent to file_seek(file, 0, FS_SEEK_SET)
*/
virtual void file_rewind(fs_file_t file);

/** Get the size of the file
/** Get the size of the file.
*
* @param file File handle
* @return Size of the file in bytes
* @param file File handle.
* @return Size of the file in bytes.
*/
virtual off_t file_size(fs_file_t file);

Expand All @@ -226,66 +226,67 @@ class FileSystem : public FileSystemLike {
* not changed. If the file is extended, the extended area appears as if
* it were zero-filled.
*
* @param file File handle
* @param length The requested new length for the file
* @param file File handle.
* @param length The requested new length for the file.
*
* @return Zero on success, negative error code on failure
* @return 0 on success, negative error code on failure.
*/
virtual int file_truncate(fs_file_t file, off_t length);

/** Open a directory on the filesystem
/** Open a directory on the file system.
*
* @param dir Destination for the handle to the directory
* @param path Name of the directory to open
* @return 0 on success, negative error code on failure
* @param dir Destination for the handle to the directory.
* @param path Name of the directory to open.
* @return 0 on success, negative error code on failure.
*/
virtual int dir_open(fs_dir_t *dir, const char *path);

/** Close a directory
/** Close a directory.
*
* @param dir Dir handle
* @return 0 on success, negative error code on failure
* @param dir Dir handle.
* @return 0 on success, negative error code on failure.
*/
virtual int dir_close(fs_dir_t dir);

/** Read the next directory entry
/** Read the next directory entry.
*
* @param dir Dir handle
* @param ent The directory entry to fill out
* @return 1 on reading a filename, 0 at end of directory, negative error on failure
* @param dir Dir handle.
* @param ent The directory entry to fill out.
* @return 1 on reading a filename, 0 at the end of the directory, negative error on failure.
*/
virtual ssize_t dir_read(fs_dir_t dir, struct dirent *ent);

/** Set the current position of the directory
/** Set the current position of the directory.
*
* @param dir Dir handle
* @param dir Dir handle.
* @param offset Offset of the location to seek to,
* must be a value returned from dir_tell
* must be a value returned from dir_tell.
*/
virtual void dir_seek(fs_dir_t dir, off_t offset);

/** Get the current position of the directory
/** Get the current position of the directory.
*
* @param dir Dir handle
* @return Position of the directory that can be passed to dir_rewind
* @param dir Dir handle.
* @return Directory position, which can be passed to dir_rewind.
*/
virtual off_t dir_tell(fs_dir_t dir);

/** Rewind the current position to the beginning of the directory
/** Rewind the current position to the beginning of the directory.
*
* @param dir Dir handle
* @param dir Dir handle.
*/
virtual void dir_rewind(fs_dir_t dir);

/** Get the sizeof the directory
/** Get the size of the directory.
*
* @param dir Dir handle
* @return Number of files in the directory
* @param dir Dir handle.
* @return Number of files in the directory.
*/
virtual size_t dir_size(fs_dir_t dir);
#endif //!defined(DOXYGEN_ONLY)

protected:
// Hooks for FileSystemHandle
// Hooks for file systemHandle
virtual int open(FileHandle **file, const char *path, int flags);
virtual int open(DirHandle **dir, const char *path);
};
Expand Down
Loading