r18739 - gnucash/trunk/src/app-utils - Doxygen fixes
Geert Janssens
gjanssens at code.gnucash.org
Fri Feb 26 10:05:23 EST 2010
Author: gjanssens
Date: 2010-02-26 10:05:23 -0500 (Fri, 26 Feb 2010)
New Revision: 18739
Trac: http://svn.gnucash.org/trac/changeset/18739
Modified:
gnucash/trunk/src/app-utils/file-utils.c
gnucash/trunk/src/app-utils/file-utils.h
Log:
Doxygen fixes
- Have this file show up under module "Utility Functions"
- Normalize the function descriptions (some were not in doxygen format)
- Add a global file description
- rename parameter 'file' to 'filename' for better consistency (note
this required an internal parameter to be renamed from filename to
new_filename)
Modified: gnucash/trunk/src/app-utils/file-utils.c
===================================================================
--- gnucash/trunk/src/app-utils/file-utils.c 2010-02-25 17:42:43 UTC (rev 18738)
+++ gnucash/trunk/src/app-utils/file-utils.c 2010-02-26 15:05:23 UTC (rev 18739)
@@ -65,42 +65,42 @@
}
/********************************************************************\
- * htmlRead *
+ * gncReadFile *
* *
- * Args: file - the name of the html file to read *
+ * Args: filename - the name of the html file to read *
* data - pointer to set to the buffer of data read in *
* Return: size of data read *
* Global: helpPath - the path to the help files *
\********************************************************************/
int
-gncReadFile (const char * file, char ** data)
+gncReadFile (const char * filename, char ** data)
{
char *buf = NULL;
- char *filename;
+ char *fullname;
int size = 0;
int fd;
/* construct absolute path -- twiddle the relative path we received */
- if (!file || file[0] == '\0') return 0;
+ if (!filename || filename[0] == '\0') return 0;
/* take absolute paths without searching */
- if (!g_path_is_absolute (file))
- filename = gncFindFile (file);
+ if (!g_path_is_absolute (filename))
+ fullname = gncFindFile (filename);
else
- filename = g_strdup (file);
+ fullname = g_strdup (filename);
- if (!filename) return 0;
+ if (!fullname) return 0;
/* Open file: */
- fd = g_open( filename, O_RDONLY, 0 );
+ fd = g_open( fullname, O_RDONLY, 0 );
- g_free(filename);
- filename = NULL;
+ g_free(fullname);
+ fullname = NULL;
if ( fd == -1 )
{
int norr = errno;
- PERR ("file %s: (%d) %s \n", file, norr, strerror(norr));
+ PERR ("file %s: (%d) %s \n", filename, norr, strerror(norr));
return 0;
}
@@ -128,7 +128,7 @@
return size;
}
-/**
+/***********************************************************************
* gnc_getline -- read a line from the input file, up to and including
* the newline.
*
Modified: gnucash/trunk/src/app-utils/file-utils.h
===================================================================
--- gnucash/trunk/src/app-utils/file-utils.h 2010-02-25 17:42:43 UTC (rev 18738)
+++ gnucash/trunk/src/app-utils/file-utils.h 2010-02-26 15:05:23 UTC (rev 18739)
@@ -25,36 +25,69 @@
* Huntington Beach, CA 92648-4632 *
\********************************************************************/
+/** @addtogroup Utils Utility functions
+ @{ */
+/** @addtogroup UtilFile File
+ * @{ */
+/** @file file-utils.h
+ * @brief Utility functions for file access
+ * @author Copyright (C) 1997 Robin D. Clark
+ * @author Copyright (C) 1998 Linas Vepstas
+ * @author Copyright (C) 1998 Rob Browning
+ * @author Copyright (C) 2004 Derek Atkins <derek at ihtfp.com>
+ *
+ * These functions help you to locate files that can reside
+ * in multiple locations.
+ */
#ifndef GNC_FILE_UTILS_H
#define GNC_FILE_UTILS_H
#include <stdio.h> /* for FILE* */
+/** Locates a file in the search path of the program and
+ * returns its absolute pathname.
+ *
+ * If the file is not found
+ * this function will return NULL.
+ *
+ * Uses the global xxxPath as the path to search
+ *
+ * @param filename The filename to search
+ *
+ * @return The absolute path to the file or NULL if the file
+ * wasn't found.
+ */
char * gncFindFile (const char * filename);
-/********************************************************************\
- * gncReadFile *
- * *
- * Args: file - the name of the html file to read *
- * data - pointer to data pointer *
- * Return: file size *
- * Global: xxxPath - the path to search *
-\********************************************************************/
-int gncReadFile (const char * file, char ** data);
+/** Reads the contents of a file into a buffer for further processing.
+ *
+ * If the filename is not an absolute filename, it will be searched
+ * for in the search path available to the program. This can be used
+ * to find for example help files,...
+ *
+ * Uses the global xxxPath as the path to search
+ *
+ * @param filename the name of the html file to read
+ *
+ * @param data Pointer to a buffer to store the file's content.
+ *
+ * @return The file size
+*/
+int gncReadFile (const char * filename, char ** data);
-/**
- * gnc_getline -- read a line from the input file, up to and including
- * the newline.
+/** Read a line from the input file, up to and including the newline.
*
- * Args: line - pointer to hold the buffer for the whole line (allocated by
- * this function)
- * file - the file from which to read
- * Return: the number of bytes read
+ * The caller MUST g_free() the line returned from this call in all
+ * cases where it is non-NULL!
*
- * The caller MUST g_free() the line returned from this call in all
- * cases where it is non-NULL!
+ * @param line pointer to hold the buffer for the whole line (allocated by
+ * this function)
+ *
+ * @param file the file from which to read
+ *
+ * @return The number of bytes read
*/
gint64 gnc_getline (gchar **line, FILE *file);
@@ -64,12 +97,13 @@
#define STATE_FILE_BOOK_GUID "BookGuid"
#define STATE_FILE_BOOK_GUID_OLD "Book Guid"
-/** Find the state file that corresponds to this URL and guid. The
- * URL is used to compute the base name of the file (which will be in
+/** Find the state file that corresponds to this URL and guid.
+ *
+ * The URL is used to compute the base name of the file (which will be in
* ~/.gnucash/books) and the guid is used to differentiate when the
* user has multiple data files with the same name.
*
- * @param url The usrl of the data file being used.
+ * @param url The url of the data file being used.
*
* @param guid The guid of the book associated with this data file.
*
@@ -81,3 +115,6 @@
GKeyFile *gnc_find_state_file (const gchar *url, const gchar *guid, gchar **filename);
#endif /* GNC_FILE_UTILS_H */
+/** @} */
+/** @} */
+
More information about the gnucash-changes
mailing list