From d0c91839036ef33a96e50e8bb6490cc9e80aa3f9 Mon Sep 17 00:00:00 2001
From: Michael Brown <mcb30@etherboot.org>
Date: Thu, 19 May 2005 14:51:37 +0000
Subject: [PATCH] Doxygenation

---
 src/arch/i386/include/bochs.h | 15 ++++--
 src/core/vsprintf.c           | 93 +++++++++++++++++++++++++++--------
 2 files changed, 84 insertions(+), 24 deletions(-)

diff --git a/src/arch/i386/include/bochs.h b/src/arch/i386/include/bochs.h
index 73f43c36..9d090fc1 100644
--- a/src/arch/i386/include/bochs.h
+++ b/src/arch/i386/include/bochs.h
@@ -1,9 +1,16 @@
 #ifndef BOCHS_H
 #define BOCHS_H
 
-/*
- * This file defines "bochsbp", the magic breakpoint instruction that
- * is incredibly useful when debugging under bochs.
+/** @file
+ *
+ * bochs breakpoints
+ *
+ * This file defines @c bochsbp, the magic breakpoint instruction that
+ * is incredibly useful when debugging under bochs.  This file should
+ * never be included in production code.
+ *
+ * Use the pseudo-instruction @c bochsbp in assembly code, or the
+ * bochsbp() function in C code.
  *
  */
 
@@ -15,7 +22,7 @@
 
 #else /* ASSEMBLY */
 
-/* Breakpoint for when debugging under bochs */
+/** Breakpoint for when debugging under bochs */
 static inline void bochsbp ( void ) {
 	__asm__ __volatile__ ( "xchgw %bx, %bx" );
 }
diff --git a/src/core/vsprintf.c b/src/core/vsprintf.c
index d5a67623..c0bc759a 100644
--- a/src/core/vsprintf.c
+++ b/src/core/vsprintf.c
@@ -10,27 +10,57 @@
 #define SHRT_SHIFT  ((int)((sizeof(unsigned short)*CHAR_BIT) - 4))
 #define CHAR_SHIFT  ((int)((sizeof(unsigned char)*CHAR_BIT) - 4))
 
-/**************************************************************************
-PRINTF and friends
+/** @file
+ *
+ * printf and friends.
+ *
+ * Etherboot's printf() functions understand the following format
+ * specifiers:
+ *
+ *	- Hexadecimal integers
+ *		- @c %[#]x	- 4 bytes int (8 hex digits, lower case)
+ *		- @c %[#]X	- 4 bytes int (8 hex digits, upper case)
+ *		- @c %[#]lx	- 8 bytes long (16 hex digits, lower case)
+ *		- @c %[#]lX	- 8 bytes long (16 hex digits, upper case)
+ *		- @c %[#]hx	- 2 bytes int (4 hex digits, lower case)
+ *		- @c %[#]hX	- 2 bytes int (4 hex digits, upper case)
+ *		- @c %[#]hhx	- 1 byte int (2 hex digits, lower case)
+ *		- @c %[#]hhX	- 1 byte int (2 hex digits, upper case)
+ *		.
+ *		If the optional # prefix is specified, the output will
+ *		be prefixed with 0x (or 0X).
+ *
+ *	- Other integers
+ *		- @c %d		- decimal int
+ *	.
+ *	Note that any width specification (e.g. the @c 02 in @c %02x)
+ *	will be accepted but ignored.
+ *
+ *	- Strings and characters
+ *		- @c %c		- char
+ *		- @c %s		- string
+ *		- @c %m		- error message text (i.e. strerror(errno))
+ *
+ *	- Etherboot-specific specifiers
+ *		- @c %@		- IP in ddd.ddd.ddd.ddd notation
+ *		- @c %!		- MAC address in xx:xx:xx:xx:xx:xx notation
+ *
+ */
 
-	Formats:
-		%[#]x	- 4 bytes int (8 hex digits, lower case)
-		%[#]X	- 4 bytes int (8 hex digits, upper case)
-		%[#]lx  - 8 bytes long (16 hex digits, lower case)
-		%[#]lX  - 8 bytes long (16 hex digits, upper case)
-		%[#]hx	- 2 bytes int (4 hex digits, lower case)
-		%[#]hX	- 2 bytes int (4 hex digits, upper case)
-		%[#]hhx	- 1 byte int (2 hex digits, lower case)
-		%[#]hhX	- 1 byte int (2 hex digits, upper case)
-			- optional # prefixes 0x or 0X
-		%d	- decimal int
-		%c	- char
-		%s	- string
-		%m	- string representation of the most recent error
-		%@	- Internet address in ddd.ddd.ddd.ddd notation
-		%!	- Ethernet address in xx:xx:xx:xx:xx:xx notation
-	Note: width specification ignored
-**************************************************************************/
+/**
+ * Write a formatted string to a buffer.
+ *
+ * @v buf		Buffer into which to write the string, or NULL
+ * @v fmt		Format string
+ * @v args		Arguments corresponding to the format string
+ * @ret len		Length of string written to buffer (if buf != NULL)
+ * @ret	0		(if buf == NULL)
+ * @err None
+ *
+ * If @c buf==NULL, then the string will be written to the console
+ * directly using putchar().
+ *
+ */
 static int vsprintf(char *buf, const char *fmt, va_list args)
 {
 	const char *p;
@@ -154,6 +184,20 @@ static int vsprintf(char *buf, const char *fmt, va_list args)
 	return (s - buf);
 }
 
+/**
+ * Write a formatted string to a buffer.
+ *
+ * @v buf		Buffer into which to write the string, or NULL
+ * @v fmt		Format string
+ * @v ...		Arguments corresponding to the format string
+ * @ret len		Length of string written to buffer (if buf != NULL)
+ * @ret	0		(if buf == NULL)
+ * @err None
+ *
+ * If @c buf==NULL, then the string will be written to the console
+ * directly using putchar().
+ *
+ */
 int sprintf(char *buf, const char *fmt, ...)
 {
 	va_list args;
@@ -164,6 +208,15 @@ int sprintf(char *buf, const char *fmt, ...)
 	return i;
 }
 
+/**
+ * Write a formatted string to the console.
+ *
+ * @v fmt		Format string
+ * @v ...		Arguments corresponding to the format string
+ * @ret	None
+ * @err None
+ *
+ */
 void printf(const char *fmt, ...)
 {
 	va_list args;