More comments in string.h

include/ucore/string.h

@@ -17,16 +17,48 @@ 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);
 
+/**
+ * Convert the string to lowercase, calls tolower() on each char.
+ * @param s string to lowercase
+ */
 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);
 
+/** Macro to calculate the number of bytes required to BCD encode
+ * the number of ascii digits
+ */
 #define UC_BCD_LEN(ascii_len) ((ascii_len) / 2 + ((ascii_len) % 2))
-#define UC_ASCII_LEN(bcd_len) ((bcd_len) * 2 + 1)
 
+/** Macro to calculate the number of bytes required to ASCII encode
+ * the number of BCD digits
+ */
+#define UC_ASCII_LEN(bcd_len) ((bcd_len) * 2)
+
+/** Convert the ascii digits to BCD. Digits not in 0..9 are skipped.
+ *
+ * @param ascii string to BCD encode.
+ * @param bcdout resulting BCD data. Must be at least UC_BCD_LEN(strlen(asciii)) big
+ * @param filler filler byte(not the ascii digit) to write in the last BCD nibble
+ *        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);
+
+/** Convert the BCD digits to ascii.
+ * The resulting ascii string is 0 terminated.
+ *
+ * @param bcd Buffer with BCD data to convert to ascii
+ * @param bcdlen number of bytes in @bcd to convert
+ * @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);
 
@@ -39,10 +71,13 @@ 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);
 
-//ocnvert bytes to a human representable test, (i.e. 12kB, 160 MB 1.78 GB etc.
+//Converts bytes to a human representable test, (i.e. 12kB, 160 MB 1.78 GB etc.)
+//Conversion is done in decimal (base 10 ,1 kB == 1000 bytes)
 ///result should be at least of size 12,
 ///returns the result argument
 char *