Clean up printf module

No functional changes.

BUG=chrome-os-partner:15579
BRANCH=none
TEST=boot system; debug output still shows up on EC console

Change-Id: I63f4f9481f5393aaff065b37a274236bd78622d9
Signed-off-by: Randall Spangler <rspangler@chromium.org>
Reviewed-on: https://gerrit.chromium.org/gerrit/36581
Reviewed-by: Bill Richardson <wfrichar@chromium.org>

2 files changed, 41 insertions, 18 deletions

diff --git a/common/printf.c b/common/printf.c
index b356e0e58a..dad02ac4c7 100644
--- a/common/printf.c
+++ b/common/printf.c
@@ -13,6 +13,13 @@ static const char error_str[] = "ERROR";
 
 #define MAX_FORMAT 1024  /* Maximum chars in a single format field */
 
+/**
+ * Convert a single digit to hex
+ *
+ * @param c	Value of digit (0 - 0x0f)
+ *
+ * @return The corresponding ASCII character ('0' - 'f').
+ */
 static int hexdigit(int c)
 {
 	return c > 9 ? (c + 'a' - 10) : (c + '0');
@@ -21,10 +28,11 @@ static int hexdigit(int c)
 int vfnprintf(int (*addchar)(void *context, int c), void *context,
 	      const char *format, va_list args)
 {
+	/*
+	 * Longest uint64 in decimal = 20
+	 * longest uint32 in binary  = 32
+	 */
 	char intbuf[34];
-		/* Longest uint64 in decimal = 20
-		 * longest uint32 in binary  = 32
-		 */
 	int dropped_chars = 0;
 	int is_left;
 	int pad_zero;
@@ -185,8 +193,10 @@ int vfnprintf(int (*addchar)(void *context, int c), void *context,
 			if (format == error_str)
 				continue; /* Bad format specifier */
 
-			/* Convert integer to string, starting at end of
-			 * buffer and working backwards. */
+			/*
+			 * Convert integer to string, starting at end of
+			 * buffer and working backwards.
+			 */
 			vstr = intbuf + sizeof(intbuf) - 1;
 			*(vstr) = '\0';
 
@@ -256,15 +266,19 @@ int vfnprintf(int (*addchar)(void *context, int c), void *context,
 	return dropped_chars ? EC_ERROR_OVERFLOW : EC_SUCCESS;
 }
 
-
 /* Context for snprintf() */
 struct snprintf_context {
 	char *str;
 	int size;
 };
 
-
-/* Add a character to the string */
+/**
+ * Add a character to the string context.
+ *
+ * @param context	Context receiving character
+ * @param c		Character to add
+ * @return 0 if character added, 1 if character dropped because no space.
+ */
 static int snprintf_addchar(void *context, int c)
 {
 	struct snprintf_context *ctx = (struct snprintf_context *)context;
@@ -277,8 +291,6 @@ static int snprintf_addchar(void *context, int c)
 	return 0;
 }
 
-
-/* Print formatted outut to a string */
 int snprintf(char *str, int size, const char *format, ...)
 {
 	struct snprintf_context ctx;
diff --git a/include/printf.h b/include/printf.h
index fdc80c2943..109fae4e2e 100644
--- a/include/printf.h
+++ b/include/printf.h
@@ -54,18 +54,29 @@
 /**
  * Print formatted output to a function, like vfprintf()
  *
- * addchar() will be called for every character to be printed, with the context
- * pointer passed to vfnprintf().  addchar() should return 0 if the character
- * was accepted or non-zero if the character was dropped due to overflow.
- *
- * Returns error if output was truncated.
+ * @param addchar	Function to be called for each character added.
+ *			Will be passed the same context passed to vfnprintf(),
+ *			and the character to add.  Should return 0 if the
+ *			character was accepted or non-zero if the character
+ *			was dropped due to overflow.
+ * @param context	Context pointer to pass to addchar()
+ * @param format	Format string (see above for acceptable formats)
+ * @param args		Parameters
+ * @return EC_SUCCESS, or non-zero if output was truncated.
  */
 int vfnprintf(int (*addchar)(void *context, int c), void *context,
 	      const char *format, va_list args);
 
-
-/* Print formatted outut to a string */
+/**
+ * Print formatted outut to a string.
+ *
+ * Guarantees null-termination if size!=0.
+ *
+ * @param str		Destination string
+ * @param size		Size of destination in bytes
+ * @param format	Format string
+ * @return EC_SUCCESS, or non-zero if output was truncated.
+ */
 int snprintf(char *str, int size, const char *format, ...);
 
-
 #endif  /* __CROS_EC_PRINTF_H */