More string.h docs, and fix style

include/ucore/string.h

@@ -8,27 +8,46 @@
 extern "C" {
 #endif
 
+/** Encode to ascii-hex, upper case letters.
+ *
+ * Subtract the return value from the passed in @out to find
+ * the length of the converted data
+ *
+ * @param in data to encode
+ * @param len length of data
+ * @param out where to store result. Must hold at least len * 2 + 1
+ * @return returns one past the end of the converted data
+ */
+char* uc_hex_encode(const uint8_t *in, size_t len, char *out);
 
-
-char*
-uc_hex_encode(const uint8_t *in, size_t len, char *out);
-uint8_t*
-uc_hex_decode(const char *in, size_t maxlen,uint8_t *out);
-char*
-uc_hex_encode_delim(const uint8_t *in, size_t inlen, char *out, int outlen, char *delim);
+/** Decode hex. Will stop at the first non-hex digit
+ * (anything not 0-9,a-f or A-F)
+ * Subtract the return value from the passed in @out to find
+ * the length of the converted data
+ *
+ * @param in data to encode
+ * @param maxlen max length of @in to convert,
+ *        conversion stops when either maxlen is reached,
+ *        nul terminator of in is found or a non hex digit is found.
+ * @param out where to store result. Must hold at least maxlen/2
+ * @return returns one past the end of the converted data
+ */
+uint8_t* uc_hex_decode(const char *in, size_t maxlen,uint8_t *out);
+/** As uc_hex_encode , but inserts the @delim string between each converted
+ *  byte (each 2 hex chars)
+ */
+char* uc_hex_encode_delim(const uint8_t *in, size_t inlen, char *out, int outlen, char *delim);
 
 /**
  * Convert the string to lowercase, calls tolower() on each char.
  * @param s string to lowercase
  */
-void 
-uc_str_tolower(char *s);
+void uc_str_tolower(char *s);
 /**
  * Convert the string to uppercase, calls toupper() on each char.
  * @param s string to uppercase
  */
-void 
-uc_str_toupper(char *s);
+void uc_str_toupper(char *s);
 
 /** Macro to calculate the number of bytes required to BCD encode
  * the number of ascii digits
@@ -48,8 +67,7 @@ uc_str_toupper(char *s);
  *        if the number of ASCII digits is odd. This would usually be 0x0 or 0xf.
  * @return the number of bytes written to bcdout
  */
-size_t 
-uc_ascii2bcd(const char *ascii, unsigned char *bcdout, unsigned char filler);
+size_t uc_ascii2bcd(const char *ascii, unsigned char *bcdout, unsigned char filler);
 
 /** Convert the BCD digits to ascii.
  * The resulting ascii string is 0 terminated.
@@ -59,33 +77,30 @@ uc_ascii2bcd(const char *ascii, unsigned char *bcdout, unsigned char filler);
  * @param asciiout buffer to place ASCII in, must be UC_ASCII_LEN(bcdlen)+1 big
  * @return the number of characters written to bcdout (this will always be UC_ASCII_LEN(bcdlen)
  */
-size_t 
-uc_bcd2ascii(const unsigned char *bcd, size_t bcdlen, char *asciiout);
+size_t uc_bcd2ascii(const unsigned char *bcd, size_t bcdlen, char *asciiout);
 
-char*
-uc_sprintb(char *result, unsigned int value);
-char*
-uc_sprintbc(char *result, unsigned char value);
-char*
-uc_sprintbll(char *result, unsigned long long value);
-char*
-uc_sprintbs(char *result, unsigned short value);
+/** uc_sprintb for converting the values into ascii bit representation
+ * e.g. 0x3 -> "00000011". The result must be able to hold the max number
+ * of bits of the type + 1. Returns 'result'
+ */
+char* uc_sprintb(char *result, unsigned int value);
+char* uc_sprintbc(char *result, unsigned char value);
+char* uc_sprintbll(char *result, unsigned long long value);
+char* uc_sprintbs(char *result, unsigned short value);
 
 /** Like http://swtch.com/plan9port/man/man3/getfields.html
  */
-int
-getfields(char *str, char **args, int max, int mflag, const char *set);
+int getfields(char *str, char **args, int max, int mflag, const char *set);
 
 //Converts bytes to a human representable test, (i.e. 12kB, 160 MB 1.78 GB etc.)
 ///result should be at least of size 12,
 ///returns the result argument
-char *
-uc_human_bytesz_dec(uint64_t bytes, char *result, size_t result_len);
+char * uc_human_bytesz_dec(uint64_t bytes, char *result, size_t result_len);
 
 //same as uc_human_bytesz_bin, but Conversion is done in binary 
 //(base 2 ,1 KiB == 1024 bytes)
-char *
-uc_human_bytesz_bin(uint64_t bytes, char *result, size_t result_len);
+char * uc_human_bytesz_bin(uint64_t bytes, char *result, size_t result_len);
+
 #ifdef __cplusplus
 }
 #endif