From 0c6c51165ba278e2d4f44dfb195d4c820930b778 Mon Sep 17 00:00:00 2001
From: Michael Poole <mdpoole@troilus.org>
Date: Tue, 5 Oct 2004 01:45:24 +0000
Subject: [PATCH] Doxyfy fileio.h and fileio.c.

git-svn-id: file:///home/klmitch/undernet-ircu/undernet-ircu-svn/ircu2/trunk@1219 c9e4aea6-c8fd-4c43-8297-357d70d61c8c
---
 include/fileio.h | 12 +++++------
 ircd/fileio.c    | 55 ++++++++++++++++++++++++++++++++++++++++++------
 2 files changed, 53 insertions(+), 14 deletions(-)

diff --git a/include/fileio.h b/include/fileio.h
index f7bf6c2..a2fcc71 100644
--- a/include/fileio.h
+++ b/include/fileio.h
@@ -1,7 +1,6 @@
-/*
- * fileio.h
- *
- * $Id$
+/** @file fileio.h
+ * @brief ANSI FILE* clone API declarations.
+ * @version $Id$
  */
 #ifndef INCLUDED_fileio_h
 #define INCLUDED_fileio_h
@@ -13,8 +12,7 @@
 
 struct stat;
 
-/*
- * FileBuf is a mirror of the ANSI FILE struct, but it works for any
+/** A mirror of the ANSI FILE struct, but it works for any
  * file descriptor. FileBufs are allocated when a file is opened with
  * fbopen, and they are freed when the file is closed using fbclose.
  * (Some OSes limit the range of file descriptors in a FILE*, for
@@ -36,7 +34,7 @@ extern FBFILE *fdbopen(int fd, const char *mode);
  * close a file opened with fbopen, see fclose(3)
  */
 extern void fbclose(FBFILE * fb);
-/* 
+/*
  * return the next character from the file, EOF on end of file
  * see fgetc(3)
  */
diff --git a/ircd/fileio.c b/ircd/fileio.c
index f6ba89d..3866786 100644
--- a/ircd/fileio.c
+++ b/ircd/fileio.c
@@ -18,6 +18,10 @@
  * along with this program; if not, write to the Free Software
  * Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
  */
+/** @file
+ * @brief ANSI FILE* clone API implementation.
+ * @version $Id$
+ */
 #include "config.h"
 
 #include "fileio.h"
@@ -30,17 +34,23 @@
 #include <unistd.h>             /* read, write, open, close */
 #include <string.h>
 
-#define FB_EOF  0x01
-#define FB_FAIL 0x02
+#define FB_EOF  0x01            /**< File has reached EOF. */
+#define FB_FAIL 0x02            /**< File operation failed. */
 
+/** Tracks status and buffer for a file on disk. */
 struct FileBuf {
-  int fd;                       /* file descriptor */
-  char *endp;                   /* one past the end */
-  char *ptr;                    /* current read pos */
-  int flags;                    /* file state */
-  char buf[BUFSIZ];             /* buffer */
+  int fd;                       /**< file descriptor */
+  char *endp;                   /**< one past the end */
+  char *ptr;                    /**< current read pos */
+  int flags;                    /**< file state */
+  char buf[BUFSIZ];             /**< buffer */
 };
 
+/** Open a new FBFILE.
+ * @param[in] filename Name of file to open.
+ * @param[in] mode fopen()-style mode string.
+ * @return Pointer to newly allocated FBFILE.
+ */
 FBFILE* fbopen(const char *filename, const char *mode)
 {
   int openmode = 0;
@@ -88,6 +98,10 @@ FBFILE* fbopen(const char *filename, const char *mode)
   return fb;
 }
 
+/** Open a FBFILE from a file descriptor.
+ * @param[in] fd File descriptor to use.
+ * @param[in] mode fopen()-style mode string (ignored).
+ */
 FBFILE* fdbopen(int fd, const char *mode)
 {
   /*
@@ -103,6 +117,9 @@ FBFILE* fdbopen(int fd, const char *mode)
   return fb;
 }
 
+/** Close a FBFILE.
+ * @param[in] fb File buffer to close.
+ */
 void fbclose(FBFILE* fb)
 {
   assert(fb);
@@ -110,6 +127,10 @@ void fbclose(FBFILE* fb)
   MyFree(fb);
 }
 
+/** Attempt to fill a file's buffer.
+ * @param[in] fb File to operate on.
+ * @return Number of bytes read into buffer, or a negative number on error.
+ */
 static int fbfill(FBFILE * fb)
 {
   int n;
@@ -129,6 +150,10 @@ static int fbfill(FBFILE * fb)
   return n;
 }
 
+/** Get a single character from a file.
+ * @param[in] fb File to fetch from.
+ * @return Character value read, or EOF on error or end-of-file.
+ */
 int fbgetc(FBFILE * fb)
 {
   assert(fb);
@@ -137,6 +162,12 @@ int fbgetc(FBFILE * fb)
   return EOF;
 }
 
+/** Get a line of input from a file.
+ * @param[out] buf Output buffer to read to.
+ * @param[in] len Maximum number of bytes to write to buffer
+ * (including terminating NUL).
+ * @param[in] fb File to read from.
+ */
 char *fbgets(char *buf, size_t len, FBFILE * fb)
 {
   char *p = buf;
@@ -173,6 +204,11 @@ char *fbgets(char *buf, size_t len, FBFILE * fb)
   return buf;
 }
 
+/** Write a string to a file.
+ * @param[in] str String to write to file.
+ * @param[in] fb File to write to.
+ * @return Number of bytes written, or -1 on error.
+ */
 int fbputs(const char *str, FBFILE * fb)
 {
   int n = -1;
@@ -187,6 +223,11 @@ int fbputs(const char *str, FBFILE * fb)
   return n;
 }
 
+/** Get file status.
+ * @param[out] sb Receives file status.
+ * @param[in] fb File to get status for.
+ * @return Zero on success, -1 on error.
+ */
 int fbstat(struct stat *sb, FBFILE * fb)
 {
   assert(sb);
-- 
2.20.1