cleanup utils header, remove cruft and add documentation

riscos/query.h

@@ -23,6 +23,24 @@
 #include "oslib/wimp.h"
 #include "utils/utils.h"
 
+enum query_response {
+  QUERY_CONTINUE,
+  QUERY_YES,
+  QUERY_NO,
+  QUERY_ESCAPE
+};
+
+typedef int query_id;
+
+#define QUERY_INVALID ((query_id)-1)
+
+typedef struct
+{
+	void (*confirm)(query_id id, enum query_response res, void *pw);
+	void (*cancel)(query_id, enum query_response res, void *pw);
+} query_callback;
+
+
 query_id query_user_xy(const char *query, const char *detail,
 	const query_callback *cb, void *pw, const char *yes, const char *no,
 	int x, int y);

utils/nsurl.c

@@ -36,6 +36,17 @@
 /* Define to enable NSURL debugging */
 #undef NSURL_DEBUG
 
+/**
+ * Return a hex digit for the given numerical value.
+ *
+ * \param digit the value to get the hex digit for.
+ * \return character in range 0-9A-F
+ */
+inline static char digit2uppercase_hex(unsigned char digit) {
+	assert(digit < 16);
+	return "0123456789ABCDEF"[digit];
+}
+
 static bool nsurl__is_unreserved(unsigned char c)
 {
 	/* From RFC3986 section 2.3 (unreserved characters) 

utils/utils.c

@@ -37,32 +37,7 @@
 #include "utils/utf8.h"
 #include "utils/utils.h"
 
-char * strip(char * const s)
+/* exported interface documented in utils/utils.h */
-{
-	size_t i;
-	for (i = strlen(s);
-			i != 0 && (s[i - 1] == ' ' || s[i - 1] == '\n' ||
-			s[i - 1] == '\r' || s[i - 1] == '\t');
-			i--)
-		;
-	s[i] = 0;
-	return s + strspn(s, " \t\r\n");
-}
-
-int whitespace(const char * str)
-{
-	unsigned int i;
-	for (i = 0; i < strlen(str); i++)
-		if (!isspace(str[i]))
-			return 0;
-	return 1;
-}
-
-/**
- * returns a string without its underscores
- * \param replacespace true to insert a space where there was an underscore
- */
-
 char *remove_underscores(const char *s, bool replacespace)
 {
 	size_t i, ii, len;
@@ -81,15 +56,8 @@ char *remove_underscores(const char *s, bool replacespace)
 	return ret;
 }
 
-/**
- * Replace consecutive whitespace with a single space.
- *
- * @todo determine if squash_whitespace utf-8 safe and that it needs to be
- *
- * \param  s  source string
- * \return  heap allocated result, or NULL on memory exhaustion
- */
 
+/* exported interface documented in utils/utils.h */
 char *squash_whitespace(const char *s)
 {
 	char *c;
@@ -116,14 +84,7 @@ char *squash_whitespace(const char *s)
 }
 
 
-/**
+/* exported interface documented in utils/utils.h */
- * Converts NUL terminated UTF-8 encoded string s containing zero or more
- * spaces (char 32) or TABs (char 9) to non-breaking spaces
- * (0xC2 + 0xA0 in UTF-8 encoding).
- *
- * Caller needs to free() result.  Returns NULL in case of error.  No
- * checking is done on validness of the UTF-8 input string.
- */
 char *cnv_space2nbsp(const char *s)
 {
 	const char *srcP;
@@ -146,10 +107,8 @@ char *cnv_space2nbsp(const char *s)
 	return d;
 }
 
-/**
- * Check if a directory exists.
- */
 
+/* exported interface documented in utils/utils.h */
 bool is_dir(const char *path)
 {
 	struct stat s;
@@ -160,6 +119,7 @@ bool is_dir(const char *path)
 	return S_ISDIR(s.st_mode) ? true : false;
 }
 
+
 /* exported interface documented in utils/utils.h */
 nserror vsnstrjoin(char **str, size_t *size, char sep, size_t nelm, va_list ap)
 {
@@ -240,12 +200,8 @@ nserror snstrjoin(char **str, size_t *size, char sep, size_t nelm, ...)
 	return ret;
 }
 
-/**
- * Compile a regular expression, handling errors.
- *
- * Parameters as for regcomp(), see man regex.
- */
 
+/* exported interface documented in utils/utils.h */
 void regcomp_wrapper(regex_t *preg, const char *regex, int cflags)
 {
 	int r;
@@ -258,24 +214,20 @@ void regcomp_wrapper(regex_t *preg, const char *regex, int cflags)
 	}
 }
 
-/** We can have a fairly good estimate of how long the buffer needs to
+/**
-  * be.  The unsigned long can store a value representing a maximum size
+ * The size of buffers within human_friendly_bytesize.
-  * of around 4 GB.  Therefore the greatest space required is to
+ *
-  * represent 1023MB.  Currently that would be represented as "1023MB" so 12
+ * We can have a fairly good estimate of how long the buffer needs to
-  * including a null terminator.
+ * be.  The unsigned long can store a value representing a maximum
-  * Ideally we would be able to know this value for sure, in the mean
+ * size of around 4 GB.  Therefore the greatest space required is to
-  * time the following should suffice.
+ * represent 1023MB.  Currently that would be represented as "1023MB"
- **/
+ * so 12 including a null terminator.  Ideally we would be able to
-
+ * know this value for sure, in the mean time the following should
+ * suffice.
+ */
 #define BYTESIZE_BUFFER_SIZE 20
 
-/**
+/* exported interface documented in utils/utils.h */
-  * Does a simple conversion which assumes the user speaks English.  The buffer
-  * returned is one of three static ones so may change each time this call is
-  * made.  Don't store the buffer for later use.  It's done this way for
-  * convenience and to fight possible memory leaks, it is not necessarily pretty.
- **/
-
 char *human_friendly_bytesize(unsigned long bsize) {
 	static char buffer1[BYTESIZE_BUFFER_SIZE];
 	static char buffer2[BYTESIZE_BUFFER_SIZE];
@@ -308,17 +260,13 @@ char *human_friendly_bytesize(unsigned long bsize) {
 		unit = gigabytes;
 	}
 
-	sprintf(curbuffer, "%3.2f%s", bytesize, messages_get(units[unit]));
+	snprintf(curbuffer, BYTESIZE_BUFFER_SIZE, "%3.2f%s", bytesize, messages_get(units[unit]));
 
 	return curbuffer;
 }
 
-/**
+
- * Create an RFC 1123 compliant date string from a Unix timestamp
+/* exported interface documented in utils/utils.h */
- *
- * \param t The timestamp to consider
- * \return Pointer to buffer containing string - invalidated by next call.
- */
 const char *rfc1123_date(time_t t)
 {
 	static char ret[30];
@@ -336,14 +284,8 @@ const char *rfc1123_date(time_t t)
 	return ret;
 }
 
-/**
+
- * Returns a number of centiseconds, that increases in real time, for the
+/* exported interface documented in utils/utils.h */
- * purposes of measuring how long something takes in wall-clock terms.  It uses
- * gettimeofday() for this.  Should the call to gettimeofday() fail, it returns
- * zero.
- *
- * \return number of centiseconds that increases monotonically
- */
 unsigned int wallclock(void)
 {
 	struct timeval tv;

utils/utils.h

@@ -17,6 +17,12 @@
  * along with this program.  If not, see <http://www.gnu.org/licenses/>.
  */
 
+/**
+ * \file utils/utils.h
+ * \brief Interface to a number of general purpose functionality.
+ * \todo Many of these functions and macros should have their own headers.
+ */
+
 #ifndef _NETSURF_UTILS_UTILS_H_
 #define _NETSURF_UTILS_UTILS_H_
 
@@ -89,27 +95,11 @@ struct dirent;
 /**
  * Calculate length of constant C string.
  *
- * \param  x	   a constant C string.
+ * \param  x a constant C string.
- * \return the length of C string without its terminating NUL accounted.
+ * \return The length of C string without its terminator.
  */
 #define SLEN(x) (sizeof((x)) - 1)
 
-enum query_response {
-  QUERY_CONTINUE,
-  QUERY_YES,
-  QUERY_NO,
-  QUERY_ESCAPE
-};
-
-typedef int query_id;
-
-#define QUERY_INVALID ((query_id)-1)
-
-typedef struct
-{
-	void (*confirm)(query_id id, enum query_response res, void *pw);
-	void (*cancel)(query_id, enum query_response res, void *pw);
-} query_callback;
 
 #ifndef timeradd
 #define timeradd(a, aa, result)						\
@@ -137,15 +127,78 @@ typedef struct
 
 
 
-char * strip(char * const s);
+/**
-int whitespace(const char * str);
+ * Replace consecutive whitespace with a single space.
+ *
+ * @todo determine if squash_whitespace utf-8 safe and that it needs to be
+ *
+ * \param  s  source string
+ * \return  heap allocated result, or NULL on memory exhaustion
+ */
 char * squash_whitespace(const char * s);
+
+/**
+ * returns a string without its underscores
+ * \param replacespace true to insert a space where there was an underscore
+ */
 char *remove_underscores(const char *s, bool replacespace);
+
+/**
+ * Converts NUL terminated UTF-8 encoded string s containing zero or more
+ * spaces (char 32) or TABs (char 9) to non-breaking spaces
+ * (0xC2 + 0xA0 in UTF-8 encoding).
+ *
+ * Caller needs to free() result.  Returns NULL in case of error.  No
+ * checking is done on validness of the UTF-8 input string.
+ */
 char *cnv_space2nbsp(const char *s);
+
+/**
+ * Check if a directory exists.
+ */
 bool is_dir(const char *path);
+
+/**
+ * Compile a regular expression, handling errors.
+ *
+ * Parameters as for regcomp(), see man regex.
+ */
 void regcomp_wrapper(regex_t *preg, const char *regex, int cflags);
+
+/**
+ * Create a human redable representation of a size in bytes.
+ *
+ * Does a simple conversion which assumes the user speaks English.
+ * The buffer returned is one of three static ones so may change each
+ * time this call is made.  Don't store the buffer for later use.
+ * It's done this way for convenience and to fight possible memory
+ * leaks, it is not necessarily pretty.
+ *
+ * @todo This implementation is strange doe sit need
+ * reconsidering?
+ *
+ * @param bsize The size in bytes.
+ * @return A human readable string representing the size.
+ */
 char *human_friendly_bytesize(unsigned long bytesize);
+
+/**
+ * Create an RFC 1123 compliant date string from a Unix timestamp
+ *
+ * \param t The timestamp to consider
+ * \return Pointer to buffer containing string - invalidated by next call.
+ */
 const char *rfc1123_date(time_t t);
+
+/**
+ * Returns a number of centiseconds, that increases in real time, for the
+ * purposes of measuring how long something takes in wall-clock terms.
+ *
+ * The implementation uses gettimeofday() for this.  Should the call
+ * to gettimeofday() fail, it returns zero.
+ *
+ * \return number of centiseconds that increases monotonically
+ */
 unsigned int wallclock(void);
 
 /**
@@ -203,27 +256,6 @@ nserror snstrjoin(char **str, size_t *size, char sep, size_t nelm, ...);
  */
 int dir_sort_alpha(const struct dirent **d1, const struct dirent **d2);
 
-/**
- * Return a hex digit for the given numerical value.
- *
- * \return character in range 0-9a-f
- */
-inline static char digit2lowcase_hex(unsigned char digit) {
-	assert(digit < 16);
-	return "0123456789abcdef"[digit];
-}
-
-/**
- * Return a hex digit for the given numerical value.
- *
- * \return character in range 0-9A-F
- */
-inline static char digit2uppercase_hex(unsigned char digit) {
-	assert(digit < 16);
-	return "0123456789ABCDEF"[digit];
-}
-
-
 /* Platform specific functions */
 void die(const char * const error);
 void warn_user(const char *warning, const char *detail);

utils/utsname.h

@@ -27,16 +27,23 @@
 #ifdef HAVE_UTSNAME
 #include <sys/utsname.h>
 #else
-/* from posix spec */
+/** system information filled in by uname derived from posix spec. */
 struct utsname {
-	char sysname[65];    /* Operating system name (e.g., "Linux") */
+	char sysname[65]; /**< Operating system name (e.g., "Linux") */
-	char nodename[65];   /* Name within "some implementation-defined
+	char nodename[65]; /**< Name within "some implementation-defined
-			      network" */
+			    * network"
-	char release[65];    /* OS release (e.g., "2.6.28") */
+			    */
-	char version[65];    /* OS version */
+	char release[65]; /**< OS release (e.g., "2.6.28") */
-	char machine[65];    /* Hardware identifier */
+	char version[65]; /**< OS version */
+	char machine[65]; /**< Hardware identifier */
 };
 
+/**
+ * Get the system information.
+ *
+ * @param buf the buffer to fill with teh information.
+ * @return 0 on sucess or -1 and errno set on faliure.
+ */
 int uname(struct utsname *buf);
 
 #endif