Doxygenation

src/core/console.c

@@ -1,31 +1,24 @@
-/*
- * Central console switch.  Various console devices can be selected
- * via the build options CONSOLE_FIRMWARE, CONSOLE_SERIAL etc.
- * config.c picks up on these definitions and drags in the relevant
- * objects.  The linker compiles the console_drivers table for us; we
- * simply delegate to each console_driver that we find in the table.
- *
- * Doing it this way allows for changing CONSOLE_XXX without
- * rebuilding anything other than config.o.  This is extremely useful
- * for rom-o-matic.
- */
-
 #include "stddef.h"
 #include "console.h"
 
-/* FIXME: we need a cleaner way to pick up cpu_nap().  It makes a
- * real-mode call, and so we don't want to use it with LinuxBIOS.
- */
+/** @file */
+
 #include "bios.h"
 
 static struct console_driver console_drivers[0] __table_start ( console );
 static struct console_driver console_drivers_end[0] __table_end ( console );
 
-/*****************************************************************************
- * putchar : write a single character to each console
- *****************************************************************************
+/**
+ * Write a single character to each console device.
+ *
+ * @v character		Character to be written
+ * @ret None
+ * @err None
+ *
+ * The character is written out to all enabled console devices, using
+ * each device's console_driver::putchar() method.
+ *
  */
-
 void putchar ( int character ) {
 	struct console_driver *console;
 
@@ -40,10 +33,18 @@ void putchar ( int character ) {
 	}
 }
 
-/*****************************************************************************
- * has_input : check to see if any input is available on any console,
- * and return a pointer to the console device if so
- *****************************************************************************
+/**
+ * Check to see if any input is available on any console.
+ *
+ * @v None
+ * @ret console		Console device that has input available, if any.
+ * @ret NULL		No console device has input available.
+ * @err None
+ *
+ * All enabled console devices are checked once for available input
+ * using each device's console_driver::iskey() method.  The first
+ * console device that has available input will be returned, if any.
+ *
  */
 static struct console_driver * has_input ( void ) {
 	struct console_driver *console;
@@ -58,13 +59,30 @@ static struct console_driver * has_input ( void ) {
 	return NULL;
 }
 
-/*****************************************************************************
- * getchar : read a single character from any console
+/**
+ * Read a single character from any console.
+ *
+ * @v None
+ * @ret character	Character read from a console.
+ * @err None
+ *
+ * A character will be read from the first enabled console device that
+ * has input available using that console's console_driver::getchar()
+ * method.  If no console has input available to be read, this method
+ * will block.  To perform a non-blocking read, use something like
+ *
+ * @code
+ *
+ *   int key = iskey() ? getchar() : -1;
+ *
+ * @endcode
+ *
+ * The character read will not be echoed back to any console.
+ *
+ * @bug We need a cleaner way to pick up cpu_nap().  It makes a
+ * real-mode call, and so we don't want to use it with LinuxBIOS.
  *
- * NOTE : this function does not echo the character, and it does block
- *****************************************************************************
  */
-
 int getchar ( void ) {
 	struct console_driver *console;
 	int character = 256;
@@ -92,11 +110,20 @@ int getchar ( void ) {
 	return character;
 }
 
-/*****************************************************************************
- * iskey : check to see if any input is available on any console
- *****************************************************************************
+/** Check for available input on any console.
+ *
+ * @v None
+ * @ret True		Input is available on a console
+ * @ret False		Input is not available on any console
+ * @err None
+ *
+ * All enabled console devices are checked once for available input
+ * using each device's console_driver::iskey() method.  If any console
+ * device has input available, this call will return True.  If this
+ * call returns True, you can then safely call getchar() without
+ * blocking.
+ *
  */
-
 int iskey ( void ) {
 	return has_input() ? 1 : 0;
 }

src/include/console.h

@@ -5,19 +5,94 @@
 #include "vsprintf.h"
 #include "tables.h"
 
-/*
- * Consoles that cannot be used before their INIT_FN() has completed
- * should set disabled = 1 initially.  This allows other console
- * devices to still be used to print out early debugging messages.
+/** @file
+ *
+ * User interaction.
+ *
+ * Various console devices can be selected via the build options
+ * CONSOLE_FIRMWARE, CONSOLE_SERIAL etc.  The console functions
+ * putchar(), getchar() and iskey() delegate to the individual console
+ * drivers.
+ *
  */
 
+/**
+ * A console driver
+ *
+ * Defines the functions that implement a particular console type.
+ * Must be made part of the console drivers table by using
+ * #__console_driver.
+ *
+ * @note Consoles that cannot be used before their INIT_FN() has
+ * completed should set #disabled=1 initially.  This allows other
+ * console devices to still be used to print out early debugging
+ * messages.
+ *
+ */
 struct console_driver {
+	/** Console is disabled.
+	 *
+	 * The console's putchar(), getchar() and iskey() methods will
+	 * not be called while #disabled==1.  Typically the
+	 * console's initialisation functions (called via INIT_FN())
+	 * will set #disabled=0 upon completion.
+	 *
+	 */
 	int disabled;
+
+	/** Write a character to the console.
+	 *
+	 * @v character		Character to be written
+	 * @ret None
+	 * @err None
+	 *
+	 */
 	void ( *putchar ) ( int character );
+
+	/** Read a character from the console.
+	 *
+	 * @v None
+	 * @ret character	Character read
+	 * @err None
+	 *
+	 * If no character is available to be read, this method will
+	 * block.  The character read should not be echoed back to the
+	 * console.
+	 *
+	 */
 	int ( *getchar ) ( void );
+
+	/** Check for available input.
+	 *
+	 * @v None
+	 * @ret True		Input is available
+	 * @ret False		Input is not available
+	 * @err None
+	 *
+	 * This should return True if a subsequent call to getchar()
+	 * will not block.
+	 *
+	 */
 	int ( *iskey ) ( void );
 };
 
+/**
+ * Mark a <tt> struct console_driver </tt> as being part of the
+ * console drivers table.
+ *
+ * Use as e.g.
+ *
+ * @code
+ *
+ *   struct console_driver my_console __console_driver = {
+ *      .putchar = my_putchar,
+ *	.getchar = my_getchar,
+ *	.iskey = my_iskey,
+ *   };
+ *
+ * @endcode
+ *
+ */
 #define __console_driver __table ( console, 01 )
 
 /* Function prototypes */