Various Doxygen comment fixes, typo fixes, etc.

 - Fix incorrect argument names for @param entries.

 - Add missing @param and @return entries, partly as TODOs.

 - s/@returns/@return/, that's a typo.
 
 - Small whitespace fixes while I'm at it.
 
 - Drop useless @brief commands, they just clutter the comments and make them
   harder to read. Doxygen has an option to always use the first sentence
   of a Doxygen-comment as @brief automatically (should be on per default).
   
Signed-off-by: Uwe Hermann <uwe@hermann-uwe.de>
Acked-by: Uwe Hermann <uwe@hermann-uwe.de>



git-svn-id: svn://svn.coreboot.org/coreboot/trunk@5955 2b7e53f0-3cfb-0310-b3e9-8179ed1497e1

10 files changed, 221 insertions, 194 deletions

diff --git a/src/devices/device.c b/src/devices/device.c
index 3f3cc57f10..d7335c95a1 100644
--- a/src/devices/device.c
+++ b/src/devices/device.c
@@ -46,23 +46,20 @@ extern struct device *last_dev;
 /** Linked list of free resources */
 struct resource *free_resources = NULL;
 
+DECLARE_SPIN_LOCK(dev_lock)
 
 /**
- * @brief Allocate a new device structure.
+ * Allocate a new device structure.
  *
- * Allocte a new device structure and attached it to the device tree as a
+ * Allocte a new device structure and attach it to the device tree as a
  * child of the parent bus.
  *
- * @param parent parent bus the newly created device attached to.
- * @param path path to the device to be created.
- *
- * @return pointer to the newly created device structure.
+ * @param parent Parent bus the newly created device should be attached to.
+ * @param path Path to the device to be created.
+ * @return Pointer to the newly created device structure.
  *
  * @see device_path
  */
-
-DECLARE_SPIN_LOCK(dev_lock)
-
 device_t alloc_dev(struct bus *parent, struct device_path *path)
 {
 	device_t dev, child;
@@ -103,10 +100,11 @@ device_t alloc_dev(struct bus *parent, struct device_path *path)
 }
 
 /**
- * @brief round a number up to an alignment.
- * @param val the starting value
- * @param roundup Alignment as a power of two
- * @returns rounded up number
+ * Round a number up to an alignment.
+ *
+ * @param val The starting value.
+ * @param roundup Alignment as a power of two.
+ * @return Rounded up number.
  */
 static resource_t round(resource_t val, unsigned long pow)
 {
@@ -117,15 +115,17 @@ static resource_t round(resource_t val, unsigned long pow)
 	return val;
 }
 
-/** Read the resources on all devices of a given bus.
- * @param bus bus to read the resources on.
+/**
+ * Read the resources on all devices of a given bus.
+ *
+ * @param bus Bus to read the resources on.
  */
 static void read_resources(struct bus *bus)
 {
 	struct device *curdev;
 
-	printk(BIOS_SPEW, "%s %s bus %x link: %d\n", dev_path(bus->dev), __func__,
-		    bus->secondary, bus->link_num);
+	printk(BIOS_SPEW, "%s %s bus %x link: %d\n", dev_path(bus->dev),
+	       __func__, bus->secondary, bus->link_num);
 
 	/* Walk through all devices and find which resources they need. */
 	for (curdev = bus->children; curdev; curdev = curdev->sibling) {
@@ -205,7 +205,8 @@ static struct device *largest_resource(struct bus *bus,
 	return state.result_dev;
 }
 
-/* Compute allocate resources is the guts of the resource allocator.
+/**
+ * Compute allocate resources is the guts of the resource allocator.
  *
  * The problem.
  *  - Allocate resource locations for every device.
@@ -231,6 +232,11 @@ static struct device *largest_resource(struct bus *bus,
  *   a device with a couple of resources, and not need to special case it in
  *   the allocator. Also this allows handling of other types of bridges.
  *
+ * @param bus The bus we are traversing.
+ * @param bridge The bridge resource which must contain the bus' resources.
+ * @param type_mask This value gets ANDed with the resource type.
+ * @param type This value must match the result of the AND.
+ * @return TODO
  */
 static void compute_resources(struct bus *bus, struct resource *bridge,
 		       unsigned long type_mask, unsigned long type)
@@ -392,8 +398,8 @@ static void compute_resources(struct bus *bus, struct resource *bridge,
  *
  * @param bus The bus we are traversing.
  * @param bridge The bridge resource which must contain the bus' resources.
- * @param type_mask This value gets anded with the resource type.
- * @param type This value must match the result of the and.
+ * @param type_mask This value gets ANDed with the resource type.
+ * @param type This value must match the result of the AND.
  */
 static void allocate_resources(struct bus *bus, struct resource *bridge,
 			unsigned long type_mask, unsigned long type)
@@ -540,10 +546,11 @@ static void allocate_resources(struct bus *bus, struct resource *bridge,
 }
 
 #if CONFIG_PCI_64BIT_PREF_MEM == 1
-	#define MEM_MASK (IORESOURCE_PREFETCH | IORESOURCE_MEM)
+#define MEM_MASK (IORESOURCE_PREFETCH | IORESOURCE_MEM)
 #else
-	#define MEM_MASK (IORESOURCE_MEM)
+#define MEM_MASK (IORESOURCE_MEM)
 #endif
+
 #define IO_MASK (IORESOURCE_IO)
 #define PREF_TYPE (IORESOURCE_PREFETCH | IORESOURCE_MEM)
 #define MEM_TYPE (IORESOURCE_MEM)
@@ -749,9 +756,7 @@ static void set_vga_bridge_bits(void)
 #endif
 
 /**
- * @brief  Assign the computed resources to the devices on the bus.
- *
- * @param bus Pointer to the structure for this bus
+ * Assign the computed resources to the devices on the bus.
  *
  * Use the device specific set_resources method to store the computed
  * resources to hardware. For bridge devices, the set_resources() method
@@ -760,6 +765,8 @@ static void set_vga_bridge_bits(void)
  * Mutual recursion:
  *	assign_resources() -> device_operation::set_resources()
  *	device_operation::set_resources() -> assign_resources()
+ *
+ * @param bus Pointer to the structure for this bus.
  */
 void assign_resources(struct bus *bus)
 {
@@ -784,9 +791,7 @@ void assign_resources(struct bus *bus)
 }
 
 /**
- * @brief Enable the resources for devices on a link
- *
- * @param link the link whose devices' resources are to be enabled
+ * Enable the resources for devices on a link.
  *
  * Enable resources of the device by calling the device specific
  * enable_resources() method.
@@ -795,6 +800,7 @@ void assign_resources(struct bus *bus)
  * order problem. This is done by calling the parent's enable_resources()
  * method before its childrens' enable_resources() methods.
  *
+ * @param link The link whose devices' resources are to be enabled.
  */
 static void enable_resources(struct bus *link)
 {
@@ -815,14 +821,10 @@ static void enable_resources(struct bus *link)
 }
 
 /**
- * @brief Reset all of the devices a bus
- *
  * Reset all of the devices on a bus and clear the bus's reset_needed flag.
  *
- * @param bus pointer to the bus structure
- *
+ * @param bus Pointer to the bus structure.
  * @return 1 if the bus was successfully reset, 0 otherwise.
- *
  */
 int reset_bus(struct bus *bus)
 {
@@ -835,7 +837,7 @@ int reset_bus(struct bus *bus)
 }
 
 /**
- * @brief Scan for devices on a bus.
+ * Scan for devices on a bus.
  *
  * If there are bridges on the bus, recursively scan the buses behind the
  * bridges. If the setting up and tuning of the bus causes a reset to be
@@ -873,7 +875,7 @@ unsigned int scan_bus(struct device *busdev, unsigned int max)
 }
 
 /**
- * @brief Determine the existence of devices and extend the device tree.
+ * Determine the existence of devices and extend the device tree.
  *
  * Most of the devices in the system are listed in the mainboard Config.lb
  * file. The device structures for these devices are generated at compile
@@ -916,7 +918,7 @@ void dev_enumerate(void)
 }
 
 /**
- * @brief Configure devices on the devices tree.
+ * Configure devices on the devices tree.
  *
  * Starting at the root of the device tree, travel it recursively in two
  * passes. In the first pass, we compute and allocate resources (ranges)
@@ -1032,7 +1034,7 @@ void dev_configure(void)
 }
 
 /**
- * @brief Enable devices on the device tree.
+ * Enable devices on the device tree.
  *
  * Starting at the root, walk the tree and enable all devices/bridges by
  * calling the device's enable_resources() method.
@@ -1051,14 +1053,13 @@ void dev_enable(void)
 }
 
 /**
- * @brief Initialize a specific device
- *
- * @param dev the device to be initialized
+ * Initialize a specific device.
  *
  * The parent should be initialized first to avoid having an ordering
  * problem. This is done by calling the parent's init()
  * method before its childrens' init() methods.
  *
+ * @param dev The device to be initialized.
  */
 static void init_dev(struct device *dev)
 {
@@ -1095,10 +1096,10 @@ static void init_link(struct bus *link)
 }
 
 /**
- * @brief Initialize all devices in the global device tree.
+ * Initialize all devices in the global device tree.
  *
- * Starting at the root device, call the device's init() method to do device-
- * specific setup, then call each child's init() method.
+ * Starting at the root device, call the device's init() method to do
+ * device-specific setup, then call each child's init() method.
  */
 void dev_initialize(void)
 {
diff --git a/src/devices/device_util.c b/src/devices/device_util.c
index 2c46884d9e..8315ce4907 100644
--- a/src/devices/device_util.c
+++ b/src/devices/device_util.c
@@ -30,12 +30,12 @@
 #include <string.h>
 
 /**
- * @brief See if a device structure exists for path
+ * See if a device structure exists for path.
  *
- * @param bus The bus to find the device on
- * @param path The relative path from the bus to the appropriate device
- * @return pointer to a device structure for the device on bus at path
- *         or 0/NULL if no device is found
+ * @param parent The bus to find the device on.
+ * @param path The relative path from the bus to the appropriate device.
+ * @return Pointer to a device structure for the device on bus at path
+ *         or 0/NULL if no device is found.
  */
 device_t find_dev_path(struct bus *parent, struct device_path *path)
 {
@@ -49,11 +49,11 @@ device_t find_dev_path(struct bus *parent, struct device_path *path)
 }
 
 /**
- * @brief See if a device structure already exists and if not allocate it
+ * See if a device structure already exists and if not allocate it.
  *
- * @param bus The bus to find the device on
- * @param path The relative path from the bus to the appropriate device
- * @return pointer to a device structure for the device on bus at path
+ * @param parent The bus to find the device on.
+ * @param path The relative path from the bus to the appropriate device.
+ * @return Pointer to a device structure for the device on bus at path.
  */
 device_t alloc_find_dev(struct bus *parent, struct device_path *path)
 {
@@ -66,11 +66,11 @@ device_t alloc_find_dev(struct bus *parent, struct device_path *path)
 }
 
 /**
- * @brief Given a PCI bus and a devfn number, find the device structure
+ * Given a PCI bus and a devfn number, find the device structure.
  *
- * @param bus The bus number
- * @param devfn a device/function number
- * @return pointer to the device structure
+ * @param bus The bus number.
+ * @param devfn A device/function number.
+ * @return Pointer to the device structure (if found), 0 otherwise.
  */
 struct device *dev_find_slot(unsigned int bus, unsigned int devfn)
 {
@@ -89,11 +89,11 @@ struct device *dev_find_slot(unsigned int bus, unsigned int devfn)
 }
 
 /**
- * @brief Given a smbus bus and a device number, find the device structure
+ * Given an SMBus bus and a device number, find the device structure.
  *
- * @param bus The bus number
- * @param addr a device number
- * @return pointer to the device structure
+ * @param bus The bus number.
+ * @param addr A device number.
+ * @return Pointer to the device structure (if found), 0 otherwise.
  */
 struct device *dev_find_slot_on_smbus(unsigned int bus, unsigned int addr)
 {
@@ -111,15 +111,18 @@ struct device *dev_find_slot_on_smbus(unsigned int bus, unsigned int addr)
         return result;
 }
 
-/** Find a device of a given vendor and type
- * @param vendor Vendor ID (e.g. 0x8086 for Intel)
- * @param device Device ID
+/**
+ * Find a device of a given vendor and type.
+ *
+ * @param vendor A PCI vendor ID (e.g. 0x8086 for Intel).
+ * @param device A PCI device ID.
  * @param from Pointer to the device structure, used as a starting point
  *        in the linked list of all_devices, which can be 0 to start at the
- *        head of the list (i.e. all_devices)
- * @return Pointer to the device struct
+ *        head of the list (i.e. all_devices).
+ * @return Pointer to the device struct.
  */
-struct device *dev_find_device(unsigned int vendor, unsigned int device, struct device *from)
+struct device *dev_find_device(unsigned int vendor, unsigned int device,
+			       struct device *from)
 {
 	if (!from)
 		from = all_devices;
@@ -131,12 +134,14 @@ struct device *dev_find_device(unsigned int vendor, unsigned int device, struct
 	return from;
 }
 
-/** Find a device of a given class
- * @param class Class of the device
+/**
+ * Find a device of a given class.
+ *
+ * @param class Class of the device.
  * @param from Pointer to the device structure, used as a starting point
  *        in the linked list of all_devices, which can be 0 to start at the
- *        head of the list (i.e. all_devices)
- * @return Pointer to the device struct
+ *        head of the list (i.e. all_devices).
+ * @return Pointer to the device struct.
  */
 struct device *dev_find_class(unsigned int class, struct device *from)
 {
@@ -149,12 +154,14 @@ struct device *dev_find_class(unsigned int class, struct device *from)
 	return from;
 }
 
-/* Warning: This function uses a static buffer.  Don't call it more than once
- * from the same print statement! */
-
+/*
+ * Warning: This function uses a static buffer. Don't call it more than once
+ * from the same print statement!
+ */
 const char *dev_path(device_t dev)
 {
 	static char buffer[DEVICE_PATH_MAX];
+
 	buffer[0] = '\0';
 	if (!dev) {
 		memcpy(buffer, "<null>", 7);
@@ -262,6 +269,8 @@ int path_eq(struct device_path *path1, struct device_path *path2)
 
 /**
  * Allocate 64 more resources to the free list.
+ *
+ * @return TODO.
  */
 static int allocate_more_resources(void)
 {
@@ -283,8 +292,14 @@ static int allocate_more_resources(void)
 
 /**
  * Remove resource res from the device's list and add it to the free list.
+ *
+ * @param dev TODO
+ * @param res TODO
+ * @param prev TODO
+ * @return TODO.
  */
-static void free_resource(device_t dev, struct resource *res, struct resource *prev)
+static void free_resource(device_t dev, struct resource *res,
+			  struct resource *prev)
 {
 	if (prev)
 		prev->next = res->next;
@@ -297,7 +312,8 @@ static void free_resource(device_t dev, struct resource *res, struct resource *p
 /**
  * See if we have unused but allocated resource structures.
  * If so remove the allocation.
- * @param dev The device to find the resource on
+ *
+ * @param dev The device to find the resource on.
  */
 void compact_resources(device_t dev)
 {
@@ -312,16 +328,17 @@ void compact_resources(device_t dev)
 	}
 }
 
-
 /**
- * See if a resource structure already exists for a given index
- * @param dev The device to find the resource on
- * @param index  The index of the resource on the device.
- * @return the resource if it already exists
+ * See if a resource structure already exists for a given index.
+ *
+ * @param dev The device to find the resource on.
+ * @param index The index of the resource on the device.
+ * @return The resource, if it already exists.
  */
 struct resource *probe_resource(device_t dev, unsigned index)
 {
 	struct resource *res;
+
 	/* See if there is a resource with the appropriate index */
 	for (res = dev->resource_list; res; res = res->next) {
 		if (res->index == index)
@@ -331,11 +348,14 @@ struct resource *probe_resource(device_t dev, unsigned index)
 }
 
 /**
- * See if a resource structure already exists for a given index and if
- * not allocate one.  Then initialize the initialize the resource
- * to default values.
- * @param dev The device to find the resource on
- * @param index  The index of the resource on the device.
+ * See if a resource structure already exists for a given index and if not
+ * allocate one.
+ *
+ * Then initialize the initialize the resource to default values.
+ *
+ * @param dev The device to find the resource on.
+ * @param index The index of the resource on the device.
+ * @return TODO.
  */
 struct resource *new_resource(device_t dev, unsigned index)
 {
@@ -378,8 +398,10 @@ struct resource *new_resource(device_t dev, unsigned index)
 
 /**
  * Return an existing resource structure for a given index.
- * @param dev The device to find the resource on
- * @param index  The index of the resource on the device.
+ *
+ * @param dev The device to find the resource on.
+ * @param index The index of the resource on the device.
+ * return TODO.
  */
 struct resource *find_resource(device_t dev, unsigned index)
 {
@@ -397,10 +419,11 @@ struct resource *find_resource(device_t dev, unsigned index)
 
 
 /**
- * @brief round a number up to the next multiple of gran
- * @param val the starting value
- * @param gran granularity we are aligning the number to.
- * @returns aligned value
+ * Round a number up to the next multiple of gran.
+ *
+ * @param val The starting value.
+ * @param gran Granularity we are aligning the number to.
+ * @return The aligned value.
  */
 static resource_t align_up(resource_t val, unsigned long gran)
 {
@@ -412,10 +435,11 @@ static resource_t align_up(resource_t val, unsigned long gran)
 }
 
 /**
- * @brief round a number up to the previous multiple of gran
- * @param val the starting value
- * @param gran granularity we are aligning the number to.
- * @returns aligned value
+ * Round a number up to the previous multiple of gran.
+ *
+ * @param val The starting value.
+ * @param gran Granularity we are aligning the number to.
+ * @return The aligned value.
  */
 static resource_t align_down(resource_t val, unsigned long gran)
 {
@@ -426,9 +450,10 @@ static resource_t align_down(resource_t val, unsigned long gran)
 }
 
 /**
- * @brief Compute the maximum address that is part of a resource
- * @param resource the resource whose limit is desired
- * @returns the end
+ * Compute the maximum address that is part of a resource.
+ *
+ * @param resource The resource whose limit is desired.
+ * @return The end.
  */
 resource_t resource_end(struct resource *resource)
 {
@@ -449,9 +474,10 @@ resource_t resource_end(struct resource *resource)
 }
 
 /**
- * @brief Compute the maximum legal value for resource->base
- * @param resource the resource whose maximum is desired
- * @returns the maximum
+ * Compute the maximum legal value for resource->base.
+ *
+ * @param resource The resource whose maximum is desired.
+ * @return The maximum.
  */
 resource_t resource_max(struct resource *resource)
 {
@@ -463,8 +489,10 @@ resource_t resource_max(struct resource *resource)
 }
 
 /**
- * @brief return the resource type of a resource
- * @param resource the resource type to decode.
+ * Return the resource type of a resource.
+ *
+ * @param resource The resource type to decode.
+ * @return TODO.
  */
 const char *resource_type(struct resource *resource)
 {
@@ -482,11 +510,14 @@ const char *resource_type(struct resource *resource)
 }
 
 /**
- * @brief print the resource that was just stored.
- * @param dev the device the stored resorce lives on
- * @param resource the resource that was just stored.
+ * Print the resource that was just stored.
+ *
+ * @param dev The device the stored resorce lives on.
+ * @param resource The resource that was just stored.
+ * @param comment TODO
  */
-void report_resource_stored(device_t dev, struct resource *resource, const char *comment)
+void report_resource_stored(device_t dev, struct resource *resource,
+			    const char *comment)
 {
 	if (resource->flags & IORESOURCE_STORED) {
 		char buf[10];
diff --git a/src/devices/hypertransport.c b/src/devices/hypertransport.c
index 674971cb94..89a41d64fc 100644
--- a/src/devices/hypertransport.c
+++ b/src/devices/hypertransport.c
@@ -23,10 +23,6 @@
  * Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA  02110-1301 USA
  */
 
-/*
-	2005.11 yhlu add let the real sb to use small uintid
-*/
-
 #include <bitops.h>
 #include <console/console.h>
 #include <device/device.h>
@@ -35,8 +31,9 @@
 #include <device/pci_ids.h>
 #include <device/hypertransport.h>
 
-/* The hypertransport link is already optimized in pre-ram code
- * so don't do it again
+/*
+ * The hypertransport link is already optimized in pre-RAM code so don't do
+ * it again.
  */
 #define OPT_HT_LINK 0
 
@@ -261,7 +258,6 @@ static int ht_setup_link(struct ht_link *prev, device_t dev, unsigned pos)
 	}
 
 	return reset_needed;
-
 }
 
 static unsigned ht_lookup_slave_capability(struct device *dev)
@@ -598,17 +594,18 @@ unsigned int hypertransport_scan_chain(struct bus *bus,
 }
 
 /**
- * @brief Scan a PCI bridge and the buses behind the bridge.
+ * Scan a PCI bridge and the buses behind the bridge.
  *
  * Determine the existence of buses behind the bridge. Set up the bridge
  * according to the result of the scan.
  *
  * This function is the default scan_bus() method for PCI bridge devices.
  *
- * @param dev pointer to the bridge device
- * @param max the highest bus number assgined up to now
- *
- * @return The maximum bus number found, after scanning all subordinate busses
+ * @param bus TODO
+ * @param min_devfn TODO
+ * @param max_devfn TODO
+ * @param max The highest bus number assgined up to now.
+ * @return The maximum bus number found, after scanning all subordinate busses.
  */
 static unsigned int hypertransport_scan_chain_x(struct bus *bus,
         unsigned min_devfn, unsigned max_devfn, unsigned int max)
@@ -623,7 +620,6 @@ unsigned int ht_scan_bridge(struct device *dev, unsigned int max)
 	return do_pci_scan_bridge(dev, max, hypertransport_scan_chain_x);
 }
 
-
 /** Default device operations for hypertransport bridges */
 static struct pci_operations ht_bus_ops_pci = {
 	.set_subsystem = 0,
diff --git a/src/devices/pci_device.c b/src/devices/pci_device.c
index 16e8d3f203..ac799c5fec 100644
--- a/src/devices/pci_device.c
+++ b/src/devices/pci_device.c
@@ -106,8 +106,9 @@ u32 pci_moving_config32(struct device * dev, unsigned int reg)
  * matching capability. Always start at the head of the list.
  *
  * @param dev Pointer to the device structure.
- * @param cap_type PCI_CAP_LIST_ID of the PCI capability we're looking for.
+ * @param cap PCI_CAP_LIST_ID of the PCI capability we're looking for.
  * @param last Location of the PCI capability register to start from.
+ * @return The next matching capability.
  */
 unsigned pci_find_next_capability(struct device *dev, unsigned cap,
 				  unsigned last)
@@ -157,7 +158,8 @@ unsigned pci_find_next_capability(struct device *dev, unsigned cap,
  * capability. Always start at the head of the list.
  *
  * @param dev Pointer to the device structure.
- * @param cap_type PCI_CAP_LIST_ID of the PCI capability we're looking for.
+ * @param cap PCI_CAP_LIST_ID of the PCI capability we're looking for.
+ * @return The next matching capability.
  */
 unsigned pci_find_capability(device_t dev, unsigned cap)
 {
@@ -169,6 +171,7 @@ unsigned pci_find_capability(device_t dev, unsigned cap)
  *
  * @param dev Pointer to the device structure.
  * @param index Address of the PCI configuration register.
+ * @return TODO
  */
 struct resource *pci_get_resource(struct device *dev, unsigned long index)
 {
@@ -373,11 +376,11 @@ static void pci_bridge_read_bases(struct device *dev)
 	/* See if the bridge I/O resources are implemented. */
 	moving_base = ((u32) pci_moving_config8(dev, PCI_IO_BASE)) << 8;
 	moving_base |=
-	    ((u32) pci_moving_config16(dev, PCI_IO_BASE_UPPER16)) << 16;
+	  ((u32) pci_moving_config16(dev, PCI_IO_BASE_UPPER16)) << 16;
 
 	moving_limit = ((u32) pci_moving_config8(dev, PCI_IO_LIMIT)) << 8;
 	moving_limit |=
-	    ((u32) pci_moving_config16(dev, PCI_IO_LIMIT_UPPER16)) << 16;
+	  ((u32) pci_moving_config16(dev, PCI_IO_LIMIT_UPPER16)) << 16;
 
 	moving = moving_base & moving_limit;
 
@@ -386,17 +389,14 @@ static void pci_bridge_read_bases(struct device *dev)
 
 	/* See if the bridge prefmem resources are implemented. */
 	moving_base =
-	    ((resource_t) pci_moving_config16(dev, PCI_PREF_MEMORY_BASE)) << 16;
+	  ((resource_t) pci_moving_config16(dev, PCI_PREF_MEMORY_BASE)) << 16;
 	moving_base |=
-	    ((resource_t) pci_moving_config32(dev, PCI_PREF_BASE_UPPER32)) <<
-	    32;
+	  ((resource_t) pci_moving_config32(dev, PCI_PREF_BASE_UPPER32)) << 32;
 
 	moving_limit =
-	    ((resource_t) pci_moving_config16(dev, PCI_PREF_MEMORY_LIMIT)) <<
-	    16;
+	  ((resource_t) pci_moving_config16(dev, PCI_PREF_MEMORY_LIMIT)) << 16;
 	moving_limit |=
-	    ((resource_t) pci_moving_config32(dev, PCI_PREF_LIMIT_UPPER32)) <<
-	    32;
+	  ((resource_t) pci_moving_config32(dev, PCI_PREF_LIMIT_UPPER32)) << 32;
 
 	moving = moving_base & moving_limit;
 	/* Initialize the prefetchable memory constraints on the current bus. */
@@ -704,7 +704,7 @@ struct device_operations default_pci_ops_bus = {
 };
 
 /**
- * @brief Detect the type of downstream bridge
+ * Detect the type of downstream bridge.
  *
  * This function is a heuristic to detect which type of bus is downstream
  * of a PCI-to-PCI bridge. This functions by looking for various capability
@@ -768,8 +768,10 @@ static struct device_operations *get_pci_bridge_ops(device_t dev)
 }
 
 /**
- * Set up PCI device operation.  Check if it already has a driver.  If not, use
- * find_device_operations, or set to a default based on type.
+ * Set up PCI device operation.
+ *
+ * Check if it already has a driver. If not, use find_device_operations(),
+ * or set to a default based on type.
  *
  * @param dev Pointer to the device whose pci_ops you want to set.
  * @see pci_drivers
@@ -827,7 +829,7 @@ static void set_pci_ops(struct device *dev)
 }
 
 /**
- * @brief See if we have already allocated a device structure for a given devfn.
+ * See if we have already allocated a device structure for a given devfn.
  *
  * Given a linked list of PCI device structures and a devfn number, find the
  * device structure correspond to the devfn, if present. This function also
@@ -835,7 +837,6 @@ static void set_pci_ops(struct device *dev)
  *
  * @param list The device structure list.
  * @param devfn A device/function number.
- *
  * @return Pointer to the device structure found or NULL if we have not
  *	   allocated a device for this devfn yet.
  */
@@ -881,18 +882,17 @@ static struct device *pci_scan_get_dev(struct device **list, unsigned int devfn)
 }
 
 /**
- * @brief Scan a PCI bus.
+ * Scan a PCI bus.
  *
  * Determine the existence of a given PCI device. Allocate a new struct device
  * if dev==NULL was passed in and the device exists in hardware.
  *
- * @param bus pointer to the bus structure
- * @param devfn to look at
- *
- * @return The device structure for hte device (if found)
- *         or the NULL if no device is found.
+ * @param dev Pointer to the dev structure.
+ * @param bus Pointer to the bus structure.
+ * @param devfn A device/function number to look at.
+ * @return The device structure for the device (if found), NULL otherwise.
  */
-device_t pci_probe_dev(device_t dev, struct bus * bus, unsigned devfn)
+device_t pci_probe_dev(device_t dev, struct bus *bus, unsigned devfn)
 {
 	u32 id, class;
 	u8 hdr_type;
@@ -989,7 +989,7 @@ device_t pci_probe_dev(device_t dev, struct bus * bus, unsigned devfn)
 }
 
 /**
- * @brief Scan a PCI bus.
+ * Scan a PCI bus.
  *
  * Determine the existence of devices and bridges on a PCI bus. If there are
  * bridges on the bus, recursively scan the buses behind the bridges.
@@ -997,12 +997,11 @@ device_t pci_probe_dev(device_t dev, struct bus * bus, unsigned devfn)
  * This function is the default scan_bus() method for the root device
  * 'dev_root'.
  *
- * @param bus pointer to the bus structure
- * @param min_devfn minimum devfn to look at in the scan usually 0x00
- * @param max_devfn maximum devfn to look at in the scan usually 0xff
- * @param max current bus number
- *
- * @return The maximum bus number found, after scanning all subordinate busses
+ * @param bus Pointer to the bus structure.
+ * @param min_devfn Minimum devfn to look at in the scan, usually 0x00.
+ * @param max_devfn Maximum devfn to look at in the scan, usually 0xff.
+ * @param max Current bus number.
+ * @return The maximum bus number found, after scanning all subordinate busses.
  */
 unsigned int pci_scan_bus(struct bus *bus,
 			  unsigned min_devfn, unsigned max_devfn,
@@ -1084,7 +1083,7 @@ unsigned int pci_scan_bus(struct bus *bus,
 }
 
 /**
- * @brief Scan a PCI bridge and the buses behind the bridge.
+ * Scan a PCI bridge and the buses behind the bridge.
  *
  * Determine the existence of buses behind the bridge. Set up the bridge
  * according to the result of the scan.
@@ -1093,6 +1092,7 @@ unsigned int pci_scan_bus(struct bus *bus,
  *
  * @param dev Pointer to the bridge device.
  * @param max The highest bus number assigned up to now.
+ * @param do_scan_bus TODO
  * @return The maximum bus number found, after scanning all subordinate buses.
  */
 unsigned int do_pci_scan_bridge(struct device *dev, unsigned int max,
@@ -1164,7 +1164,7 @@ unsigned int do_pci_scan_bridge(struct device *dev, unsigned int max,
 }
 
 /**
- * @brief Scan a PCI bridge and the buses behind the bridge.
+ * Scan a PCI bridge and the buses behind the bridge.
  *
  * Determine the existence of buses behind the bridge. Set up the bridge
  * according to the result of the scan.
@@ -1181,14 +1181,13 @@ unsigned int pci_scan_bridge(struct device *dev, unsigned int max)
 }
 
 /**
- * @brief Scan a PCI domain.
+ * Scan a PCI domain.
  *
  * This function is the default scan_bus() method for PCI domains.
  *
- * @param dev pointer to the domain
- * @param max the highest bus number assgined up to now
- *
- * @return The maximum bus number found, after scanning all subordinate busses
+ * @param dev Pointer to the domain.
+ * @param max The highest bus number assigned up to now.
+ * @return The maximum bus number found, after scanning all subordinate busses.
  */
 unsigned int pci_domain_scan_bus(device_t dev, unsigned int max)
 {
@@ -1198,8 +1197,7 @@ unsigned int pci_domain_scan_bus(device_t dev, unsigned int max)
 
 #if CONFIG_PC80_SYSTEM == 1
 /**
- *
- * @brief Assign IRQ numbers
+ * Assign IRQ numbers.
  *
  * This function assigns IRQs for all functions contained within the indicated
  * device address.  If the device does not exist or does not require interrupts
@@ -1207,12 +1205,11 @@ unsigned int pci_domain_scan_bus(device_t dev, unsigned int max)
  *
  * This function should be called for each PCI slot in your system.
  *
- * @param bus
- * @param slot
- * @param pIntAtoD is an array of IRQ #s that are assigned to PINTA through
- *        PINTD of this slot.  The particular irq #s that are passed in
- *        depend on the routing inside your southbridge and on your
- *        motherboard.
+ * @param bus Pointer to the bus structure.
+ * @param slot TODO
+ * @param pIntAtoD An array of IRQ #s that are assigned to PINTA through PINTD
+ *        of this slot. The particular IRQ #s that are passed in depend on the
+ *        routing inside your southbridge and on your board.
  */
 void pci_assign_irqs(unsigned bus, unsigned slot,
 	const unsigned char pIntAtoD[4])
diff --git a/src/devices/pci_ops.c b/src/devices/pci_ops.c
index 60ed1ca280..c3237dbdbf 100644
--- a/src/devices/pci_ops.c
+++ b/src/devices/pci_ops.c
@@ -25,7 +25,8 @@
 #include <device/pci_ids.h>
 #include <device/pci_ops.h>
 
-/* The only consumer of the return value of get_pbus() is ops_pci_bus().
+/*
+ * The only consumer of the return value of get_pbus() is ops_pci_bus().
  * ops_pci_bus() can handle being passed NULL and auto-picks working ops.
  */
 static struct bus *get_pbus(device_t dev)
diff --git a/src/devices/pci_rom.c b/src/devices/pci_rom.c
index f13d9b6768..50351b43dc 100644
--- a/src/devices/pci_rom.c
+++ b/src/devices/pci_rom.c
@@ -29,7 +29,7 @@
 #include <string.h>
 #include <cbfs.h>
 
-struct rom_header * pci_rom_probe(struct device *dev)
+struct rom_header *pci_rom_probe(struct device *dev)
 {
 	struct rom_header *rom_header;
 	struct pci_data *rom_data;
diff --git a/src/devices/pciexp_device.c b/src/devices/pciexp_device.c
index 790029ef1e..f304545b74 100644
--- a/src/devices/pciexp_device.c
+++ b/src/devices/pciexp_device.c
@@ -24,7 +24,6 @@
 #include <device/pci_ids.h>
 #include <device/pciexp.h>
 
-
 static void pciexp_tune_dev(device_t dev)
 {
 	unsigned cap;
@@ -63,7 +62,6 @@ unsigned int pciexp_scan_bus(struct bus *bus,
 	return max;
 }
 
-
 unsigned int pciexp_scan_bridge(device_t dev, unsigned int max)
 {
 	return do_pci_scan_bridge(dev, max, pciexp_scan_bus);
diff --git a/src/devices/pcix_device.c b/src/devices/pcix_device.c
index 0fcedd5e45..42babe79dd 100644
--- a/src/devices/pcix_device.c
+++ b/src/devices/pcix_device.c
@@ -24,7 +24,6 @@
 #include <device/pci_ids.h>
 #include <device/pcix.h>
 
-
 static void pcix_tune_dev(device_t dev)
 {
 	unsigned cap;
@@ -130,7 +129,6 @@ unsigned int pcix_scan_bridge(device_t dev, unsigned int max)
 	return max;
 }
 
-
 /** Default device operations for PCI-X bridges */
 static struct pci_operations pcix_bus_ops_pci = {
 	.set_subsystem = 0,
diff --git a/src/devices/root_device.c b/src/devices/root_device.c
index cd576a15b6..2c5cfd84e1 100644
--- a/src/devices/root_device.c
+++ b/src/devices/root_device.c
@@ -28,9 +28,10 @@
 #include <reset.h>
 
 /**
- * Read the resources for the root device,
- * that encompass the resources for the entire system.
- * @param root Pointer to the device structure for the system root device
+ * Read the resources for the root device, that encompass the resources for
+ * the entire system.
+ *
+ * @param root Pointer to the device structure for the system root device.
  */
 static void root_dev_read_resources(device_t root)
 {
@@ -38,11 +39,12 @@ static void root_dev_read_resources(device_t root)
 }
 
 /**
- * @brief Write the resources for every device
+ * Write the resources for every device.
+ *
+ * Write the resources for the root device, and every device under it which
+ * are all of the devices.
  *
- * Write the resources for the root device,
- * and every device under it which are all of the devices.
- * @param root Pointer to the device structure for the system root device
+ * @param root Pointer to the device structure for the system root device.
  */
 static void root_dev_set_resources(device_t root)
 {
@@ -50,7 +52,7 @@ static void root_dev_set_resources(device_t root)
 }
 
 /**
- * @brief Scan devices on static buses.
+ * Scan devices on static buses.
  *
  * The enumeration of certain buses is purely static. The existence of
  * devices on those buses can be completely determined at compile time
@@ -67,8 +69,8 @@ static void root_dev_set_resources(device_t root)
  * This function is the default scan_bus() method for the root device and
  * LPC bridges.
  *
- * @param bus Pointer to the device structure which the static buses are attached
- * @param max  Maximum bus number currently used before scanning.
+ * @param bus Pointer to the device to which the static buses are attached to.
+ * @param max Maximum bus number currently used before scanning.
  * @return Largest bus number used.
  */
 static int smbus_max = 0;
@@ -120,12 +122,13 @@ static void root_dev_enable_resources(device_t dev)
 }
 
 /**
- * @brief Scan root bus for generic systems
- *
- * @param root The root device structure
- * @param max The current bus number scanned so far, usually 0x00
+ * Scan root bus for generic systems.
  *
  * This function is the default scan_bus() method of the root device.
+ *
+ * @param root The root device structure.
+ * @param max The current bus number scanned so far, usually 0x00.
+ * @return TODO.
  */
 static unsigned int root_dev_scan_bus(device_t root, unsigned int max)
 {
@@ -143,10 +146,10 @@ static void root_dev_reset(struct bus *bus)
 }
 
 /**
- * @brief Default device operation for root device
+ * Default device operation for root device.
  *
  * This is the default device operation for root devices. These operations
- * should be fully usable as is.  However the chip_operations::enable_dev()
+ * should be fully usable as is. However the chip_operations::enable_dev()
  * of a motherboard can override this if you want non-default behavior.
  */
 struct device_operations default_dev_ops_root = {
diff --git a/src/devices/smbus_ops.c b/src/devices/smbus_ops.c
index 4a61e87a98..9d134619b8 100644
--- a/src/devices/smbus_ops.c
+++ b/src/devices/smbus_ops.c
@@ -38,11 +38,15 @@ struct bus *get_pbus_smbus(device_t dev)
 	return pbus;
 }
 
-/*multi level i2c MUX??? may need to find the first i2c device and then set link
- * down to current dev
-  1 store get_pbus_smbus list link
-  2 reverse the link and call set link */
-
+/*
+ * Multi-level I2C MUX? may need to find the first i2c device and then set link
+ * down to current dev.
+ *
+ * 1 store get_pbus_smbus list link
+ * 2 reverse the link and call set link.
+ *
+ * @param dev TODO.
+ */
 int smbus_set_link(device_t dev)
 {
 	struct bus *pbus_a[4]; // 4 level mux only. Enough?
@@ -110,5 +114,3 @@ int smbus_block_write(device_t dev, uint8_t cmd, uint8_t bytes, const uint8_t *b
 {
 	return ops_smbus_bus(get_pbus_smbus(dev))->block_write(dev, cmd, bytes, buffer);
 }
-
-