Final fixes to the AGPGART and RADEONFB modules' documentation.

6 files changed, 59 insertions, 55 deletions

diff --git a/src/kernel/agpgart/agp.c b/src/kernel/agpgart/agp.c
index 2345e6e0bf8..7e8d3c8ab64 100644
--- a/src/kernel/agpgart/agp.c
+++ b/src/kernel/agpgart/agp.c
@@ -99,7 +99,7 @@ int agp_backend_acquire(void)
 /** 
  * Release the AGP backend. 
  *
- * The caller must insure that the graphics
+ * The caller must ensure that the graphics
  * aperture translation table is read for use
  * by another entity.  (Ensure that all memory
  * it bound is unbound.)
@@ -481,8 +481,8 @@ int agp_unbind_memory(agp_memory * curr)
 /**
  * \sa agp_bridge_data::agp_enable.
  *
- * Goes trhough all devices that claim to be AGP devices collecting their data,
- * and disabling impossible settings. Decides the 4X/2X/1X setting and enable
+ * Goes trhough all devices that claim to be AGP devices collecting their data
+ * and disabling impossible settings. Decides the 4X/2X/1X setting and enables
  * the AGP bridge device.
  */
 void agp_generic_agp_enable(u32 mode)
@@ -779,7 +779,7 @@ int agp_generic_free_gatt_table(void)
  * \sa agp_bridge_data::insert_memory.
  *
  * Makes some sanity checks, points each page entry in the GATT table to the
- * respective page of \p mem, and calls the agp_bridge_data::tbl_flush method.
+ * respective page of \p mem, and calls the agp_bridge_data::tlb_flush method.
  */
 int agp_generic_insert_memory(agp_memory * mem, off_t pg_start, int type)
 {
@@ -1401,7 +1401,7 @@ static struct _agp_bridge_info {
  * 
  * Searches agp_bridge_info for a matching vendor and device ID's and calls the
  * function in _agp_bridge_info::chipset_setup field. If the user requested
- * (agp_try_unsupported is set) and there is a \e generic bridge entry (zero
+ * (::agp_try_unsupported is set) and there is a \e generic bridge entry (zero
  * device ID) try it.
  */
 static int __init agp_lookup_host_bridge (struct pci_dev *pdev)
diff --git a/src/kernel/agpgart/agpgart.h b/src/kernel/agpgart/agpgart.h
index 6819e228fa2..a59cac8281a 100644
--- a/src/kernel/agpgart/agpgart.h
+++ b/src/kernel/agpgart/agpgart.h
@@ -236,11 +236,11 @@ typedef struct _agp_file_private {
 /** Frontend data. */
 struct agp_front_data {
 	struct semaphore agp_mutex;	/**< device mutex. \sa #AGP_INIT, #AGP_LOCK and #AGP_UNLOCK */
-	agp_controller *current_controller;
-	agp_controller *controllers;
+	agp_controller *current_controller;	/**< current controller */
+	agp_controller *controllers;	/**< controllers list */
 	agp_file_private *file_priv_list;	/**< file private data doubly linked list */
 	u8 used_by_controller;
-	u8 backend_acquired;
+	u8 backend_acquired;		/**< whether the backend has been acquired */
 };
 
 #endif				/* __KERNEL__ */
diff --git a/src/kernel/agpgart/frontend.c b/src/kernel/agpgart/frontend.c
index f11da4b95a0..5350bded124 100644
--- a/src/kernel/agpgart/frontend.c
+++ b/src/kernel/agpgart/frontend.c
@@ -48,7 +48,7 @@
 static struct agp_front_data agp_fe;
 
 /**
- * Find a agp_memory by its allocation tag.
+ * Find an agp_memory structure by its allocation tag.
  *
  * \param key allocation tag.
  * \return pointer to the agp_memory on success or NULL on failure.
@@ -75,7 +75,7 @@ static agp_memory *agp_find_mem_by_key(int key)
 }
 
 /**
- * Removes a entry from its memory pool.
+ * Removes an entry from its memory pool.
  *
  * \param temp pointer to the agp_memory structure.
  * 
@@ -155,7 +155,7 @@ static agp_segment_priv *agp_find_seg_in_client(const agp_client * client,
  *
  * \param client client information.
  *
- * Frees the agp_client::segments and its  first entry if not null.
+ * Frees the agp_client::segments and what it's pointed by it if not null.
  */
 static void agp_remove_seg_from_client(agp_client * client)
 {
@@ -383,7 +383,7 @@ void agp_remove_file_private(agp_file_private * priv)
 /*@{*/
 
 /**
- * Wrappers for agp_free_memory().
+ * Wrapper for agp_free_memory().
  *
  * Makes sure that internal lists are kept updated by calling
  * agp_remove_from_pool().
@@ -395,7 +395,7 @@ static void agp_free_memory_wrap(agp_memory * memory)
 }
 
 /**
- * Wrappers for agp_allocate_memory().
+ * Wrapper for agp_allocate_memory().
  *
  * Makes sure that internal lists are kept updated by calling
  * agp_insert_into_pool().
@@ -451,7 +451,7 @@ static agp_controller *agp_find_controller_by_pid(pid_t id)
  * \param id process id of the new controller.
  * \return pointer to the agp_controller structure on success, or NULL on failure.
  * 
- * Allocate and initialize a agp_controller structure.
+ * Allocate and initialize an agp_controller structure.
  */
 static agp_controller *agp_create_controller(pid_t id)
 {
@@ -755,7 +755,7 @@ static void agp_insert_client(agp_client * client)
  * \param id client process id.
  * \return a pointer to an agp_client structure.
  *
- * Allocate and initialze an agp_client structure and inserts into the current
+ * Allocate and initialize an agp_client structure and inserts into the current
  * controller.
  */
 static agp_client *agp_create_client(pid_t id)
@@ -915,14 +915,14 @@ static int agp_mmap(struct file *file, struct vm_area_struct *vma)
  * \param file file pointer.
  * \return zero on success or a negative number on failure.
  * 
- * If it's a controller then find its data structure, and removes it. If it's
+ * If it's a controller then finds its data structure and removes it. If it's
  * the current controller then additionally calls
  * agp_controller_release_current().
  * 
  * If it's a client then simply remove the client.
  *
  * The AGP lock is held during the function call and the file private data is
- * free before returning.
+ * freed before returning.
  */
 static int agp_release(struct inode *inode, struct file *file)
 {
@@ -959,12 +959,12 @@ static int agp_release(struct inode *inode, struct file *file)
  * \param file file pointer.
  * \return zero on success or a negative number on failure.
  * 
- * Allocate and create a agp_file_private structure for the file private data,
- * and sets the client allow flag. If the user or the suid is zero then set the
- * controller allow flag too.
+ * Allocate and create an agp_file_private structure for the file private data,
+ * and sets the client allow flag. If the user or the suid is zero then sets the
+ * <i>controller allow</i> flag too.
  *
- * If there is a client with the current proccess id then set the client and
- * valid flags.
+ * If there is a client with the current proccess id then set the \e client and
+ * \e valid flags.
  * 
  * The AGP lock is held during the function call.
  */
@@ -1032,7 +1032,7 @@ static ssize_t agp_write(struct file *file, const char *buf,
  * information will be copied.
  * \return zero on success or a negative number on failure.
  *
- * Calls agp_copy_info(), transfers the information into a agp_info structure
+ * Calls agp_copy_info(), transfers the information into an agp_info structure
  * and copies into user space.
  */
 static int agpioc_info_wrap(agp_file_private * priv, unsigned long arg)
@@ -1275,7 +1275,7 @@ static int agpioc_allocate_wrap(agp_file_private * priv, unsigned long arg)
  * \param arg allocation tag.
  * \return zero on success or a negative number on failure.
  *
- * Wrapper around agp_deallocate_memory_wrap(), using the allocation tag as
+ * Wrapper around agp_free_memory_wrap(), using the allocation tag as
  * reference.
  */
 static int agpioc_deallocate_wrap(agp_file_private * priv, unsigned long arg)
diff --git a/src/kernel/agpgart/i8x0_agp.c b/src/kernel/agpgart/i8x0_agp.c
index c453abca7a1..c41b8257d20 100644
--- a/src/kernel/agpgart/i8x0_agp.c
+++ b/src/kernel/agpgart/i8x0_agp.c
@@ -44,7 +44,7 @@
  *
  * \return always zero.
  *
- * Reads the aperture size and points agp_bridge_data::previous_size and
+ * Reads the aperture size from the hardware and points agp_bridge_data::previous_size and
  * agp_bridge_data::current_size to the agp_bridge_data::aperture_sizes entry
  * with the matching aperture size.
  */
@@ -130,7 +130,7 @@ static void intel_8xx_tlbflush(agp_memory * mem)
 /** 
  * Backend cleanup -- Intel generic.
  *
- * Sets the previous aperture size.
+ * Resets the hardware using the previous aperture size.
  */
 static void intel_cleanup(void)
 {
@@ -168,7 +168,7 @@ static void intel_8xx_cleanup(void)
  *
  * \return always zero.
  *
- * Sets the hardware registers with the information in agp_bridge_data.
+ * Updates the hardware registers to match the information in agp_bridge_data.
  */
 static int intel_configure(void)
 {
@@ -569,7 +569,8 @@ static struct aper_size_info_8 intel_830mp_sizes[4] =
  * \return always zero.
  * 
  * Initializes the device dependent part agp_bride_data structure in agp_bride,
- * using the the functions above for the driver callbacks.
+ * using a mixture of the functions above and the generic driver functions in
+ * agp.c for the driver callbacks.
  */
 int __init intel_generic_setup (struct pci_dev *pdev)
 {
diff --git a/src/kernel/fbdev/radeonfb-2.5/Doxyfile b/src/kernel/fbdev/radeonfb-2.5/Doxyfile
index 97bcfb4124d..d94974f5b1c 100644
--- a/src/kernel/fbdev/radeonfb-2.5/Doxyfile
+++ b/src/kernel/fbdev/radeonfb-2.5/Doxyfile
@@ -843,6 +843,7 @@ INCLUDE_FILE_PATTERNS  =
 
 PREDEFINED             = \
 			__KERNEL__ \
+			"__attribute__(x)=" \
 			"__devinit=" \
 			"__init=" \
 			"__devinitdata=" \
diff --git a/src/kernel/fbdev/radeonfb-2.5/radeonfb.c b/src/kernel/fbdev/radeonfb-2.5/radeonfb.c
index be8decde359..d35d4db8f29 100644
--- a/src/kernel/fbdev/radeonfb-2.5/radeonfb.c
+++ b/src/kernel/fbdev/radeonfb-2.5/radeonfb.c
@@ -464,7 +464,7 @@ static struct fb_var_screeninfo radeonfb_default_var = {
 	} while (0)
 
 
-/** Read a PLL register */
+/** Read a PLL register (inline) */
 static __inline__ u32 _INPLL(struct radeonfb_info *rinfo, u32 addr)
 {
 	OUTREG8(CLOCK_CNTL_INDEX, addr & 0x0000003f);
@@ -486,8 +486,8 @@ static __inline__ u32 _INPLL(struct radeonfb_info *rinfo, u32 addr)
  * Get monitor name.
  *
  * \param type monitor type.
- * \return pointer to a string describing the monitor type, or NULL if an
- * invalid type.
+ * \return pointer to a string describing the monitor type or NULL if \p type
+ * is invalid.
  */
 static char *GET_MON_NAME(int type)
 {
@@ -610,16 +610,16 @@ static __inline__ int _max(int val1, int val2)
  */
 /*@{*/
         
-static char *mode_option __initdata;	/**< mode option */
-static char mirror = 0;			/**< whether to enable the mirroring of
+static char *mode_option __initdata;	/**< Mode option */
+static char mirror = 0;			/**< Whether to enable the mirroring of
 					  the main display on the external CRTC
 					  */
-static int panel_yres __initdata = 0;	/**< panel vertical resolution, used
+static int panel_yres __initdata = 0;	/**< Panel vertical resolution, used
 					  when no DFP information is available */
-static char force_dfp __initdata = 0;	/**< whether to force the recognition
-					  of a DFP (Digital Flap Panel) */
+static char force_dfp __initdata = 0;	/**< Whether to force the recognition
+					  of a DFP */
 static struct radeonfb_info *board_list = NULL;	/**< list of all boards */
-static char nomtrr __initdata = 0;	/**< whether to prevent the use of MTRR's */
+static char nomtrr __initdata = 0;	/**< Whether to prevent the use of MTRR's */
 
 /*@}*/
 
@@ -729,7 +729,7 @@ static char *radeon_find_rom(struct radeonfb_info *rinfo)
  * \param rinfo framebuffer device private data.
  * \param bios_seg pointer to the BIOS segment, or NULL if not available.
  *
- * Attempts to read the PLL Basic Information from the BIOS, otherwise use the
+ * Attempts to read the PLL Basic Information Block from the BIOS, otherwise use the
  * defaults for the PLL data in radeondb_info::pll.
  */
 static void radeon_get_pllinfo(struct radeonfb_info *rinfo, char *bios_seg)
@@ -817,7 +817,8 @@ static void radeon_get_pllinfo(struct radeonfb_info *rinfo, char *bios_seg)
  *
  * \param rinfo framebuffer device private data.
  *
- * Determines the monitor type in all ports. Overriden ::force_dfp is set.
+ * Determines the monitor type in all present ports from the hardware. If
+ * ::force_dfp is set the detection of a DFP is forced.
  */
 static void radeon_get_moninfo (struct radeonfb_info *rinfo)
 {
@@ -883,6 +884,7 @@ static void radeon_get_EDID(struct radeonfb_info *rinfo)
  * \param rinfo framebuffer device private data.
  * \return non-zero on success, or zero on failure.
  *
+ * Reads the EDID timing information into \p rinfo. 
  * radeonfb_info::got_dfpinfo is set on success.
  */
 static int radeon_dfp_parse_EDID(struct radeonfb_info *rinfo)
@@ -1123,7 +1125,7 @@ static int radeon_get_dfpinfo (struct radeonfb_info *rinfo)
  * \return zero on success, or a negative number on failure.
  *
  * Calls radeon_init_disp_var() to find and initialize the user defined part of
- * the display, and activate it.
+ * the display, and activates it.
  */
 static int __devinit radeon_init_disp (struct radeonfb_info *rinfo)
 {
@@ -1189,11 +1191,11 @@ static int radeon_init_disp_var (struct radeonfb_info *rinfo,
  * \param v updated user defined part of the display.
  * \param nom numeration for the video RAM size calculation.
  * \param den denominator for the video RAM size calculation.
- * \return zero on success, or a negative number if it's impossible to find a
- * virtual resolution that fits into video memory, or a invalid resolution was
+ * \return zero on success or a negative number if it's impossible to find a
+ * virtual resolution that fits into video memory or a invalid resolution was
  * given.
  *
- * Replace the special value of -1 in the virtual resolution with the highest
+ * Replaces the special value of -1 in the virtual resolution with the highest
  * possible that will fit the video RAM, using a resolution table when both
  * horizontal and vertical resolutions have the value of -1.
  *
@@ -1386,7 +1388,7 @@ static int radeonfb_check_var (struct fb_var_screeninfo *var, struct fb_info *in
  * \return zero on success, or a negative value on failure.
  * 
  * Checks that displayed area is inside the virtual resolution and, if the
- * device it not asleep, updates the CRTC offsets.
+ * device it not asleep, updates the hardware.
  */
 static int radeonfb_pan_display (struct fb_var_screeninfo *var,
                                  struct fb_info *info)
@@ -1516,9 +1518,8 @@ static int radeonfb_ioctl (struct inode *inode, struct file *file, unsigned int
  * \param info framebuffer device data.
  * \return zero on success, or a negative value on failure.
  * 
- * If not asleep, blank the display by updating the LVDS_GEN_CNTL or
- * CRTC_EXT_CNTL for LCDs or all others monitors respectively.  Always
- * successful.
+ * If not asleep, updates the hardware to blank (or not) the display according
+ * to \p blank.  Always successful.
  */
 static int radeonfb_blank (int blank, struct fb_info *info)
 {
@@ -1659,7 +1660,7 @@ static int radeonfb_setcolreg (unsigned regno, unsigned red, unsigned green,
  * \param rinfo framebuffer device private data.
  * \param save registers structure to save the state.
  *
- * Saves the values of the registers in \p save.
+ * Reads the values of the hardware state registers saves them into \p save.
  */
 static void radeon_save_state (struct radeonfb_info *rinfo,
                                struct radeon_regs *save)
@@ -2040,8 +2041,8 @@ static int radeonfb_set_par (struct fb_info *info)
  * \param rinfo framebuffer device private data.
  * \param mode register state.
  * 
- * Sets the common registers and the mode registers while having the screen in
- * power down mode.
+ * Write all common and state (mode) registers to the hardware. This is done
+ * with the screen in power down mode.
  */
 static void radeon_write_mode (struct radeonfb_info *rinfo,
                                struct radeon_regs *mode)
@@ -2170,8 +2171,8 @@ static struct fb_ops radeonfb_ops = {
  * \param rinfo framebuffer device private data.
  * \return zero on success or a negative value on failure.
  *
- * Sets the framebuffer device information in radeonfb_info::info and
- * initializes the display.
+ * Initializes the framebuffer device information in radeonfb_info::info and
+ * initializes the display by calling radeon_init_disp().
  */
 static int __devinit radeon_set_fbinfo (struct radeonfb_info *rinfo)
 {
@@ -2219,8 +2220,9 @@ static int __devinit radeon_set_fbinfo (struct radeonfb_info *rinfo)
  * Enables the PCI device, allocates and initializes a radeonfb_info structure
  * as driver private data, finds and maps the MMIO and framebuffer regions,
  * calls radeon_set_fbinfo() to setup the framebuffer device and registers it.
- * * Before switching the mode saves the current mode registers to restore when
- * exiting.  If supported by the kernel and ::nomttrr not set then creates a
+ * 
+ * Before switching the mode it saves the current mode registers to restore when
+ * exiting.  If supported by the kernel and ::nomttrr isn't set then creates a
  * MTRR over the framebuffer region.
  */
 static int radeonfb_pci_register (struct pci_dev *pdev,
@@ -2533,7 +2535,7 @@ void __exit radeonfb_exit (void)
  *
  * \param options options.
  *
- * Updates the global variables according with the options given.
+ * Updates the global variables according with the given options.
  */
 int __init radeonfb_setup (char *options)
 {