score: Doxygen Clean Up Task #12

http://www.google-melange.com/gci/task/view/google/gci2012/8110207

20 files changed, 446 insertions, 134 deletions

diff --git a/cpukit/score/cpu/avr/avr/io90pwm81.h b/cpukit/score/cpu/avr/avr/io90pwm81.h
index cc013b96b0..753c94e008 100644
--- a/cpukit/score/cpu/avr/avr/io90pwm81.h
+++ b/cpukit/score/cpu/avr/avr/io90pwm81.h
@@ -1,3 +1,11 @@
+/**
+ * @file
+ *
+ * @brief Definitions for AT90PWM81
+ *
+ * This file should only be included from <avr/io.h>, never directly.
+ */
+
 /* Copyright (c) 2009 Atmel Corporation
    All rights reserved.
 
@@ -43,6 +51,13 @@
 #  error "Attempt to include more than one <avr/ioXXX.h> file."
 #endif 
 
+/**
+ * @defgroup AvrDef_io90pwm81 AT90PWM81 Definitions
+ *
+ * @ingroup avr
+ *
+ * @{
+ */
 
 #ifndef _AVR_AT90PWM81_H_
 #define _AVR_AT90PWM81_H_ 1
@@ -1019,6 +1034,7 @@
 #define SIGNATURE_1 0x93
 #define SIGNATURE_2 0x88
 
+/** @} */
 
 #endif /* _AVR_AT90PWM81_H_ */
 
diff --git a/cpukit/score/cpu/avr/avr/io90pwmx.h b/cpukit/score/cpu/avr/avr/io90pwmx.h
index f2db6097f7..1367424563 100644
--- a/cpukit/score/cpu/avr/avr/io90pwmx.h
+++ b/cpukit/score/cpu/avr/avr/io90pwmx.h
@@ -1,3 +1,11 @@
+/**
+ * @file
+ *
+ * @brief Definitions for AT90PWM2(B) and AT90PWM3(B)
+ *
+ * This file should only be included from <avr/io.h>, never directly.
+ */
+
 /* Copyright (c) 2005, Andrey Pashchenko
    All rights reserved.
 
@@ -46,6 +54,14 @@
 #  error "Attempt to include more than one <avr/ioXXX.h> file."
 #endif 
 
+/**
+ * @defgroup io90pwmx AT90PWM2(B) and AT90PWM3(B) Definitions
+ *
+ * @ingroup avr
+ *
+ * @{
+ */
+
 /* I/O registers */
 
 /* Port B Input Pins Address */
@@ -1366,5 +1382,6 @@
 #define __BOOT_LOCK_BITS_0_EXIST
 #define __BOOT_LOCK_BITS_1_EXIST 
 
+/** @} */
 
 #endif /* _AVR_IO90PWMX_H_ */
diff --git a/cpukit/score/cpu/avr/avr/iom164.h b/cpukit/score/cpu/avr/avr/iom164.h
index 9b97f21df6..f9607d8963 100644
--- a/cpukit/score/cpu/avr/avr/iom164.h
+++ b/cpukit/score/cpu/avr/avr/iom164.h
@@ -1,3 +1,9 @@
+/**
+ * @file
+ *
+ * @brief Definitions for ATmega164
+ */
+
 /* Copyright (c) 2005, 2006 Anatoly Sokolov
    All rights reserved.
 
@@ -36,6 +42,14 @@
 
 #include <avr/iomxx4.h>
 
+/**
+ * @defgroup AvrDef_iom164 ATmega164 Definitions
+ *
+ * @ingroup avr
+ *
+ * @{
+ */
+
 /* Constants */
 #define SPM_PAGESIZE    128
 #define RAMEND          0x04FF
@@ -89,5 +103,6 @@
 #define SIGNATURE_1 0x94
 #define SIGNATURE_2 0x0A 
 
+/** @} */
 
 #endif /* _AVR_IOM164_H_ */
diff --git a/cpukit/score/cpu/avr/avr/iom165.h b/cpukit/score/cpu/avr/avr/iom165.h
index a15eea43c2..f165d6b45c 100644
--- a/cpukit/score/cpu/avr/avr/iom165.h
+++ b/cpukit/score/cpu/avr/avr/iom165.h
@@ -1,3 +1,11 @@
+/**
+ * @file
+ *
+ * @brief Definitions for ATmega165
+ *
+ * This file should only be included from <avr/io.h>, never directly.
+ */
+
 /* Copyright (c) 2004,2005,2006 Eric B. Weddington
    All rights reserved.
 
@@ -46,6 +54,14 @@
 #  error "Attempt to include more than one <avr/ioXXX.h> file."
 #endif 
 
+/**
+ * @defgroup AvrDef_iom165 ATmega165 Definitions
+ *
+ * @ingroup avr
+ *
+ * @{
+ */
+
 /* Registers and associated bit numbers */
 
 #define PINA    _SFR_IO8(0x00)
@@ -815,5 +831,6 @@
 #define SIGNATURE_1 0x94
 #define SIGNATURE_2 0x07
 
+/** @} */
 
 #endif /* _AVR_IOM165_H_ */
diff --git a/cpukit/score/cpu/avr/avr/iom169.h b/cpukit/score/cpu/avr/avr/iom169.h
index 88a757e2ec..d99eaa8bd1 100644
--- a/cpukit/score/cpu/avr/avr/iom169.h
+++ b/cpukit/score/cpu/avr/avr/iom169.h
@@ -1,3 +1,11 @@
+/**
+ * @file
+ *
+ * @brief Definitions for ATmega169
+ *
+ * This file should only be included from <avr/io.h>, never directly.
+ */
+
 /* Copyright (c) 2002, 2003, 2004, 2005 
    Juergen Schilling <juergen.schilling@honeywell.com>
    Eric B. Weddington
@@ -50,6 +58,14 @@
 #  error "Attempt to include more than one <avr/ioXXX.h> file."
 #endif 
 
+/**
+ * @defgroup AvrDef_iom169 ATmega169 Definitions
+ *
+ * @ingroup avr
+ *
+ * @{
+ */
+
 /* I/O registers */
 
 /* Port A */
@@ -1102,5 +1118,6 @@
 #define SIGNATURE_1 0x94
 #define SIGNATURE_2 0x05
 
+/** @} */
 
 #endif  /* _AVR_IOM169_H_ */
diff --git a/cpukit/score/cpu/avr/avr/iom169p.h b/cpukit/score/cpu/avr/avr/iom169p.h
index 6aad286fc7..66427ce88c 100644
--- a/cpukit/score/cpu/avr/avr/iom169p.h
+++ b/cpukit/score/cpu/avr/avr/iom169p.h
@@ -1,3 +1,11 @@
+/**
+ * @file
+ *
+ * @brief Definitions for ATmega169P
+ *
+ * This file should only be included from <avr/io.h>, never directly.
+ */
+
 /* Copyright (c) 2002, 2003, 2004, 2005, 2006
    Juergen Schilling <juergen.schilling@honeywell.com>
    Eric B. Weddington <ericw@evcohs.com>
@@ -49,6 +57,14 @@
 #  error "Attempt to include more than one <avr/ioXXX.h> file."
 #endif 
 
+/**
+ * @defgroup AvrDef_iom169p ATmega169P Definitions
+ *
+ * @ingroup avr
+ *
+ * @{
+ */
+
 /* I/O registers */
 
 /* Port A */
@@ -1025,5 +1041,6 @@
 #define SIGNATURE_1 0x94
 #define SIGNATURE_2 0x05
 
+/** @} */
 
 #endif  /* _AVR_IOM169P_H_ */
diff --git a/cpukit/score/cpu/avr/avr/iom16hva.h b/cpukit/score/cpu/avr/avr/iom16hva.h
index cae9194539..3c5c2f54fe 100644
--- a/cpukit/score/cpu/avr/avr/iom16hva.h
+++ b/cpukit/score/cpu/avr/avr/iom16hva.h
@@ -1,3 +1,9 @@
+/**
+ * @file
+ *
+ * @brief Definitions for ATmega16HVA
+ */
+
 /* Copyright (c) 2007, Anatoly Sokolov 
    All rights reserved.
 
@@ -36,6 +42,14 @@
 
 #include <avr/iomxxhva.h>
 
+/**
+ * @defgroup AvrDef_iom16hva ATmega16HVA Definitions
+ *
+ * @ingroup avr
+ *
+ * @{
+ */
+
 /* Constants */
 #define SPM_PAGESIZE 128
 #define RAMEND      0x2FF
@@ -70,5 +84,6 @@
 #define SIGNATURE_1 0x94
 #define SIGNATURE_2 0x0C
 
+/** @} */
 
 #endif /* _AVR_IOM16HVA_H_ */
diff --git a/cpukit/score/cpu/avr/avr/iom325.h b/cpukit/score/cpu/avr/avr/iom325.h
index d22911c8e9..2427c95154 100644
--- a/cpukit/score/cpu/avr/avr/iom325.h
+++ b/cpukit/score/cpu/avr/avr/iom325.h
@@ -1,3 +1,11 @@
+/**
+ * @file
+ *
+ * @brief Definitions for ATmega325 and ATmega325P
+ *
+ * This file should only be included from <avr/io.h>, never directly.
+ */
+
 /* Copyright (c) 2004, 2005, 2006, 2007 Eric B. Weddington
    All rights reserved.
 
@@ -46,6 +54,14 @@
 #  error "Attempt to include more than one <avr/ioXXX.h> file."
 #endif 
 
+/**
+ * @defgroup AvrDef_iom325  ATmega325 and ATmega325P Definitions
+ *
+ * @ingroup avr
+ *
+ * @{
+ */
+
 /* Registers and associated bit numbers */
 
 #define PINA    _SFR_IO8(0x00)
@@ -816,5 +832,6 @@
 #define SIGNATURE_1 0x95
 #define SIGNATURE_2 0x05
 
+/** @} */
 
 #endif /* _AVR_IOM325_H_ */
diff --git a/cpukit/score/cpu/avr/avr/iom328p.h b/cpukit/score/cpu/avr/avr/iom328p.h
index 179f0a5e2d..9436f4aaf2 100644
--- a/cpukit/score/cpu/avr/avr/iom328p.h
+++ b/cpukit/score/cpu/avr/avr/iom328p.h
@@ -1,3 +1,11 @@
+/**
+ * @file
+ *
+ * @brief Definitions for ATmega328P
+ *
+ * This file should only be included from <avr/io.h>, never directly.
+ */
+
 /* Copyright (c) 2007 Atmel Corporation
    All rights reserved.
 
@@ -48,6 +56,14 @@
 #ifndef _AVR_IOM328P_H_
 #define _AVR_IOM328P_H_ 1
 
+/**
+ * @defgroup AvrDef_iom328p ATmega328P Definitions
+ *
+ * @ingroup avr
+ *
+ * @{
+ */
+
 /* Registers and associated bit numbers */
 
 #define PINB _SFR_IO8(0x03)
@@ -870,5 +886,6 @@
 #define SIGNATURE_1 0x95
 #define SIGNATURE_2 0x0F
 
+/** @} */
 
 #endif  /* _AVR_IOM328P_H_ */
diff --git a/cpukit/score/cpu/avr/avr/iom32u4.h b/cpukit/score/cpu/avr/avr/iom32u4.h
index 87f3b360ad..53d4d05ad0 100644
--- a/cpukit/score/cpu/avr/avr/iom32u4.h
+++ b/cpukit/score/cpu/avr/avr/iom32u4.h
@@ -1,3 +1,11 @@
+/**
+ * @file
+ *
+ * @brief Definitions for ATmega32U4
+ *
+ * This file should only be included from <avr/io.h>, never directly.
+ */
+
 /* Copyright (c) 2008 Atmel Corporation
    All rights reserved.
 
@@ -48,6 +56,13 @@
 #ifndef _AVR_IOM32U4_H_
 #define _AVR_IOM32U4_H_ 1
 
+/**
+ * @defgroup AvrDef_iom32u4 ATmega32U4 Definitions
+ *
+ * @ingroup avr
+ *
+ * @{
+ */
 
 /* Registers and associated bit numbers */
 
@@ -1498,6 +1513,6 @@
 #define SIGNATURE_1 0x95
 #define SIGNATURE_2 0x87
 
-
+/** @} */
 
 #endif  /* _AVR_IOM32U4_H_ */
diff --git a/cpukit/score/cpu/avr/avr/iom644.h b/cpukit/score/cpu/avr/avr/iom644.h
index 2ad996c647..5c9f113d8e 100644
--- a/cpukit/score/cpu/avr/avr/iom644.h
+++ b/cpukit/score/cpu/avr/avr/iom644.h
@@ -1,3 +1,9 @@
+/**
+ * @file
+ *
+ * @brief Definitions for ATmega644
+ */
+
 /* Copyright (c) 2005 Anatoly Sokolov
    All rights reserved.
 
@@ -36,6 +42,14 @@
 
 #include <avr/iomxx4.h>
 
+/**
+ * @defgroup AvrDef_iom644 ATmega644 Definitions
+ *
+ * @ingroup avr
+ *
+ * @{
+ */
+
 /* Constants */
 #define SPM_PAGESIZE 256
 #define RAMEND       0x10FF
@@ -89,5 +103,6 @@
 #define SIGNATURE_1 0x96
 #define SIGNATURE_2 0x09
 
+/** @} */
 
 #endif /* _AVR_IOM644_H_ */
diff --git a/cpukit/score/cpu/avr/avr/iom8hva.h b/cpukit/score/cpu/avr/avr/iom8hva.h
index 804ff526bf..a0649b6d84 100644
--- a/cpukit/score/cpu/avr/avr/iom8hva.h
+++ b/cpukit/score/cpu/avr/avr/iom8hva.h
@@ -1,3 +1,9 @@
+/**
+ * @file
+ *
+ * @brief Definitions for ATmega8HVA
+ */
+
 /* Copyright (c) 2007, Anatoly Sokolov 
    All rights reserved.
 
@@ -36,6 +42,14 @@
 
 #include <avr/iomxxhva.h>
 
+/**
+ * @defgroup AvrDef_iom8hva ATmega8HVA Definitions
+ *
+ * @ingroup avr
+ *
+ * @{
+ */
+
 /* Constants */
 #define SPM_PAGESIZE 128
 #define RAMEND      0x2FF
@@ -64,6 +78,7 @@
 /* Lock Bits */
 #define __LOCK_BITS_EXIST
 
+/** @} */
 
 #endif /* _AVR_IOM8HVA_H_ */
 
diff --git a/cpukit/score/cpu/avr/avr/iom8u2.h b/cpukit/score/cpu/avr/avr/iom8u2.h
index 24c8ff12d8..1c480233db 100644
--- a/cpukit/score/cpu/avr/avr/iom8u2.h
+++ b/cpukit/score/cpu/avr/avr/iom8u2.h
@@ -1,3 +1,11 @@
+/**
+ * @file
+ *
+ * @brief Definitions for ATmega8U2
+ *
+ * This file should only be included from <avr/io.h>, never directly.
+ */
+
 /* Copyright (c) 2009 Atmel Corporation
    All rights reserved.
 
@@ -47,6 +55,13 @@
 #ifndef _AVR_ATmega8U2_H_
 #define _AVR_ATmega8U2_H_ 1
 
+/**
+ * @defgroup AvrDef_iom8u2 ATmega8U2 Definitions
+ *
+ * @ingroup avr
+ *
+ * @{
+ */
 
 /* Registers and associated bit numbers. */
 
@@ -960,7 +975,9 @@
 #define SIGNATURE_1 0x93
 #define SIGNATURE_2 0x89
 
-
 /* Device Pin Definitions */
+
+/** @} */
+
 #endif /* _AVR_ATmega8U2_H_ */
 
diff --git a/cpukit/score/cpu/avr/avr/iotn167.h b/cpukit/score/cpu/avr/avr/iotn167.h
index 0717faaada..a98e17d4ba 100644
--- a/cpukit/score/cpu/avr/avr/iotn167.h
+++ b/cpukit/score/cpu/avr/avr/iotn167.h
@@ -1,3 +1,11 @@
+/**
+ * @file
+ *
+ * @brief Definitions for ATtiny167
+ *
+ * This file should only be included from <avr/io.h>, never directly.
+ */
+
 /* Copyright (c) 2008 Atmel Corporation
    All rights reserved.
 
@@ -48,6 +56,13 @@
 #ifndef _AVR_IOTN167_H_
 #define _AVR_IOTN167_H_ 1
 
+/**
+ * @defgroup AvrDef_iotn167 ATtiny167 Definitions
+ *
+ * @ingroup avr
+ *
+ * @{
+ */
 
 /* Registers and associated bit numbers */
 
@@ -826,6 +841,6 @@
 #define SIGNATURE_1 0x94
 #define SIGNATURE_2 0x87
 
-
+/** @} */
 
 #endif  /* _AVR_IOTN167_H_ */
diff --git a/cpukit/score/cpu/avr/avr/iotn2313.h b/cpukit/score/cpu/avr/avr/iotn2313.h
index 9495acabb6..7a2885fde9 100644
--- a/cpukit/score/cpu/avr/avr/iotn2313.h
+++ b/cpukit/score/cpu/avr/avr/iotn2313.h
@@ -1,3 +1,11 @@
+/**
+ * @file
+ *
+ * @brief Definitions for ATtiny2313
+ *
+ * This file should only be included from <avr/io.h>, never directly.
+ */
+
 /* Copyright (c) 2004, 2005, 2006 Bob Paddock
    All rights reserved.
 
@@ -71,6 +79,14 @@
 #  error "Attempt to include more than one <avr/ioXXX.h> file."
 #endif
 
+/**
+ * @defgroup AvrDef_iotn2313 ATtiny2313 Definitions
+ *
+ * @ingroup avr
+ *
+ * @{
+ */
+
 /* I/O registers */
 
 /*
@@ -628,5 +644,6 @@
 #define SIGNATURE_1 0x91
 #define SIGNATURE_2 0x0A
 
+/** @} */
 
 #endif  /* _AVR_IOTN2313_H_ */
diff --git a/cpukit/score/cpu/avr/avr/iotn28.h b/cpukit/score/cpu/avr/avr/iotn28.h
index e91d67ae11..e20985eb43 100644
--- a/cpukit/score/cpu/avr/avr/iotn28.h
+++ b/cpukit/score/cpu/avr/avr/iotn28.h
@@ -1,3 +1,11 @@
+/**
+ * @file
+ *
+ * @brief Definitions for ATtiny28
+ *
+ * This file should only be included from <avr/io.h>, never directly.
+ */
+
 /* Copyright (c) 2002, Marek Michalkiewicz
    All rights reserved.
 
@@ -50,6 +58,14 @@
 #  warning "MCU not supported by the C compiler"
 #endif
 
+/**
+ * @defgroup AvrDef_iotn28 ATtiny28 Definitions
+ *
+ * @ingroup avr
+ *
+ * @{
+ */
+
 /* I/O registers */
 
 #define OSCCAL	_SFR_IO8(0x00)
@@ -270,5 +286,6 @@
 #define SIGNATURE_1 0x91
 #define SIGNATURE_2 0x07
 
+/** @} */
 
 #endif /* _AVR_IOTN28_H_ */
diff --git a/cpukit/score/cpu/avr/avr/iotn461.h b/cpukit/score/cpu/avr/avr/iotn461.h
index 2867e3e41a..2fd1457673 100644
--- a/cpukit/score/cpu/avr/avr/iotn461.h
+++ b/cpukit/score/cpu/avr/avr/iotn461.h
@@ -1,3 +1,9 @@
+/**
+ * @file
+ *
+ * @brief Definitions for ATtiny461
+ */
+
 /* Copyright (c) 2006, Anatoly Sokolov
    All rights reserved.
 
@@ -36,6 +42,14 @@
 
 #include <avr/iotnx61.h>
 
+/**
+ * @defgroup AvrDef_iotn461 ATtiny461 Definitions
+ *
+ * @ingroup avr
+ *
+ * @{
+ */
+
 /* Constants */
 #define SPM_PAGESIZE 64
 #define RAMEND       0x15F
@@ -84,5 +98,6 @@
 #define SIGNATURE_1 0x92
 #define SIGNATURE_2 0x08
 
+/** @} */
 
 #endif /* _AVR_IOTN461_H_ */
diff --git a/cpukit/score/cpu/avr/avr/iotn88.h b/cpukit/score/cpu/avr/avr/iotn88.h
index 427fc8fd4d..afae9efa10 100644
--- a/cpukit/score/cpu/avr/avr/iotn88.h
+++ b/cpukit/score/cpu/avr/avr/iotn88.h
@@ -1,3 +1,11 @@
+/**
+ * @file
+ *
+ * @brief Definitions for ATtiny88
+ *
+ * This file should only be included from <avr/io.h>, never directly.
+ */
+
 /* Copyright (c) 2007 Atmel Corporation
    All rights reserved.
 
@@ -44,6 +52,13 @@
 #  error "Attempt to include more than one <avr/ioXXX.h> file."
 #endif 
 
+/**
+ * @defgroup AvrDef_iotn88 ATtiny88 Definitions
+ *
+ * @ingroup avr
+ *
+ * @{
+ */
 
 #ifndef _AVR_IOTN88_H_
 #define _AVR_IOTN88_H_ 1
@@ -752,5 +767,6 @@
 #define SIGNATURE_1 0x93
 #define SIGNATURE_2 0x11
 
+/** @} */
 
 #endif /* _AVR_IOTN88_H_ */
diff --git a/cpukit/score/cpu/avr/avr/iousb647.h b/cpukit/score/cpu/avr/avr/iousb647.h
index 3b93048149..b4e05a9d0a 100644
--- a/cpukit/score/cpu/avr/avr/iousb647.h
+++ b/cpukit/score/cpu/avr/avr/iousb647.h
@@ -1,3 +1,9 @@
+/**
+ * @file
+ *
+ * @brief Definitions for AT90USB647
+ */
+
 /* Copyright (c) 2006 Anatoly Sokolov 
    All rights reserved.
 
@@ -36,6 +42,14 @@
 
 #include <avr/iousbxx6_7.h>
 
+/**
+ * @defgroup AvrDef_iousb647 AT90USB647 Definitions
+ *
+ * @ingroup avr
+ *
+ * @{
+ */
+
 /* Constants */
 #define SPM_PAGESIZE 256
 #define RAMEND       0x10FF
@@ -89,5 +103,6 @@
 #define SIGNATURE_1 0x96
 #define SIGNATURE_2 0x82
 
+/** @} */
 
 #endif /* _AVR_AT90USB647_H_ */
diff --git a/cpukit/score/cpu/avr/avr/sfr_defs.h b/cpukit/score/cpu/avr/avr/sfr_defs.h
index b687f56167..c2ebe6931b 100644
--- a/cpukit/score/cpu/avr/avr/sfr_defs.h
+++ b/cpukit/score/cpu/avr/avr/sfr_defs.h
@@ -1,3 +1,9 @@
+/**
+ * @file
+ *
+ * @brief Macros for Accessing AVR Special Function Registers
+ */
+
 /* Copyright (c) 2002, Marek Michalkiewicz <marekm@amelek.gda.pl>
    All rights reserved.
 
@@ -34,85 +40,90 @@
 #ifndef _AVR_SFR_DEFS_H_
 #define _AVR_SFR_DEFS_H_ 1
 
-/** \defgroup avr_sfr_notes Additional notes from <avr/sfr_defs.h>
-    \ingroup avr_sfr
-
-   The \c <avr/sfr_defs.h> file is included by all of the \c <avr/ioXXXX.h>
-   files, which use macros defined here to make the special function register
-   definitions look like C variables or simple constants, depending on the
-   <tt>_SFR_ASM_COMPAT</tt> define.  Some examples from \c <avr/iocanxx.h> to
-   show how to define such macros:
-
-\code
-#define PORTA   _SFR_IO8(0x02)
-#define EEAR    _SFR_IO16(0x21)
-#define UDR0    _SFR_MEM8(0xC6)
-#define TCNT3   _SFR_MEM16(0x94)
-#define CANIDT  _SFR_MEM32(0xF0)
-\endcode
-
-   If \c _SFR_ASM_COMPAT is not defined, C programs can use names like
-   <tt>PORTA</tt> directly in C expressions (also on the left side of
-   assignment operators) and GCC will do the right thing (use short I/O
-   instructions if possible).  The \c __SFR_OFFSET definition is not used in
-   any way in this case.
-
-   Define \c _SFR_ASM_COMPAT as 1 to make these names work as simple constants
-   (addresses of the I/O registers).  This is necessary when included in
-   preprocessed assembler (*.S) source files, so it is done automatically if
-   \c __ASSEMBLER__ is defined.  By default, all addresses are defined as if
-   they were memory addresses (used in \c lds/sts instructions).  To use these
-   addresses in \c in/out instructions, you must subtract 0x20 from them.
-
-   For more backwards compatibility, insert the following at the start of your
-   old assembler source file:
-
-\code
-#define __SFR_OFFSET 0
-\endcode
-
-   This automatically subtracts 0x20 from I/O space addresses, but it's a
-   hack, so it is recommended to change your source: wrap such addresses in
-   macros defined here, as shown below.  After this is done, the
-   <tt>__SFR_OFFSET</tt> definition is no longer necessary and can be removed.
-
-   Real example - this code could be used in a boot loader that is portable
-   between devices with \c SPMCR at different addresses.
-
-\verbatim
-<avr/iom163.h>: #define SPMCR _SFR_IO8(0x37)
-<avr/iom128.h>: #define SPMCR _SFR_MEM8(0x68)
-\endverbatim
-
-\code
-#if _SFR_IO_REG_P(SPMCR)
-	out	_SFR_IO_ADDR(SPMCR), r24
-#else
-	sts	_SFR_MEM_ADDR(SPMCR), r24
-#endif
-\endcode
-
-   You can use the \c in/out/cbi/sbi/sbic/sbis instructions, without the
-   <tt>_SFR_IO_REG_P</tt> test, if you know that the register is in the I/O
-   space (as with \c SREG, for example).  If it isn't, the assembler will
-   complain (I/O address out of range 0...0x3f), so this should be fairly
-   safe.
-
-   If you do not define \c __SFR_OFFSET (so it will be 0x20 by default), all
-   special register addresses are defined as memory addresses (so \c SREG is
-   0x5f), and (if code size and speed are not important, and you don't like
-   the ugly \#if above) you can always use lds/sts to access them.  But, this
-   will not work if <tt>__SFR_OFFSET</tt> != 0x20, so use a different macro
-   (defined only if <tt>__SFR_OFFSET</tt> == 0x20) for safety:
-
-\code
-	sts	_SFR_ADDR(SPMCR), r24
-\endcode
-
-   In C programs, all 3 combinations of \c _SFR_ASM_COMPAT and
-   <tt>__SFR_OFFSET</tt> are supported - the \c _SFR_ADDR(SPMCR) macro can be
-   used to get the address of the \c SPMCR register (0x57 or 0x68 depending on
-   device). */
+/**
+ * @defgroup avr_sfr_notes Additional notes from <avr/sfr_defs.h>
+ *
+ * @ingroup avr_sfr
+ *
+ * The @c <avr/sfr_defs.h> file is included by all of the @c <avr/ioXXXX.h>
+ * files, which use macros defined here to make the special function register
+ * definitions look like C variables or simple constants, depending on the
+ * <tt>_SFR_ASM_COMPAT</tt> define.  Some examples from @c <avr/iocanxx.h> to
+ * show how to define such macros:
+ *
+ * @code
+ * #define PORTA   _SFR_IO8(0x02)
+ * #define EEAR    _SFR_IO16(0x21)
+ * #define UDR0    _SFR_MEM8(0xC6)
+ * #define TCNT3   _SFR_MEM16(0x94)
+ * #define CANIDT  _SFR_MEM32(0xF0)
+ * @endcode
+ *
+ * If @c _SFR_ASM_COMPAT is not defined, C programs can use names like
+ * <tt>PORTA</tt> directly in C expressions (also on the left side of
+ * assignment operators) and GCC will do the right thing (use short I/O
+ * instructions if possible).  The @c __SFR_OFFSET definition is not used in
+ * any way in this case.
+ *
+ * Define @c _SFR_ASM_COMPAT as 1 to make these names work as simple constants
+ * (addresses of the I/O registers).  This is necessary when included in
+ * preprocessed assembler (*.S) source files, so it is done automatically if
+ * @c __ASSEMBLER__ is defined.  By default, all addresses are defined as if
+ * they were memory addresses (used in @c lds/sts instructions).  To use these
+ * addresses in @c in/out instructions, you must subtract 0x20 from them.
+ *
+ * For more backwards compatibility, insert the following at the start of your
+ * old assembler source file:
+ *
+ * @code
+ * #define __SFR_OFFSET 0
+ * @endcode
+ *
+ * This automatically subtracts 0x20 from I/O space addresses, but it's a
+ * hack, so it is recommended to change your source: wrap such addresses in
+ * macros defined here, as shown below.  After this is done, the
+ * <tt>__SFR_OFFSET</tt> definition is no longer necessary and can be removed.
+
+ * Real example - this code could be used in a boot loader that is portable
+ * between devices with @c SPMCR at different addresses.
+ *
+ * @verbatim
+ * <avr/iom163.h>: #define SPMCR _SFR_IO8(0x37)
+ * <avr/iom128.h>: #define SPMCR _SFR_MEM8(0x68)
+ * @endverbatim
+ *
+ * @code
+ * #if _SFR_IO_REG_P(SPMCR)
+ * 	out	_SFR_IO_ADDR(SPMCR), r24
+ * #else
+ *	sts	_SFR_MEM_ADDR(SPMCR), r24
+ * #endif
+ * @endcode
+ *
+ * You can use the @c in/out/cbi/sbi/sbic/sbis instructions, without the
+ * <tt>_SFR_IO_REG_P</tt> test, if you know that the register is in the I/O
+ * space (as with @c SREG, for example).  If it isn't, the assembler will
+ * complain (I/O address out of range 0...0x3f), so this should be fairly
+ * safe.
+ *
+ * If you do not define @c __SFR_OFFSET (so it will be 0x20 by default), all
+ * special register addresses are defined as memory addresses (so @c SREG is
+ * 0x5f), and (if code size and speed are not important, and you don't like
+ * the ugly \#if above) you can always use lds/sts to access them.  But, this
+ * will not work if <tt>__SFR_OFFSET</tt> != 0x20, so use a different macro
+ * (defined only if <tt>__SFR_OFFSET</tt> == 0x20) for safety:
+ *
+ * @code
+ *	sts	_SFR_ADDR(SPMCR), r24
+ * @endcode
+ *
+ * In C programs, all 3 combinations of @c _SFR_ASM_COMPAT and
+ * <tt>__SFR_OFFSET</tt> are supported - the @c _SFR_ADDR(SPMCR) macro can be
+ * used to get the address of the @c SPMCR register (0x57 or 0x68 depending on
+ * device).
+ *
+ * @{
+ */
 
 #ifdef __ASSEMBLER__
 #define _SFR_ASM_COMPAT 1
@@ -190,23 +201,24 @@
 #define _SFR_WORD(sfr) _MMIO_WORD(_SFR_ADDR(sfr))
 #define _SFR_DWORD(sfr) _MMIO_DWORD(_SFR_ADDR(sfr))
 
-/** \name Bit manipulation */
-
-/*@{*/
-/** \def _BV
-    \ingroup avr_sfr
-
-    \code #include <avr/io.h>\endcode
-
-    Converts a bit number into a byte value.
-
-    \note The bit shift is performed by the compiler which then inserts the
-    result into the code. Thus, there is no run-time overhead when using
-    _BV(). */
-    
+/**
+ * @name Bit Manipulation
+ *
+ * @{
+ */
+
+/**
+ * @code #include <avr/io.h> @endcode
+ *
+ * Converts a bit number into a byte value.
+ *
+ * @note The bit shift is performed by the compiler which then inserts the
+ *       result into the code. Thus, there is no run-time overhead when using
+ *       _BV().
+ */   
 #define _BV(bit) (1 << (bit))
 
-/*@}*/
+/** @} */
 
 #ifndef _VECTOR
 #define _VECTOR(N) __vector_ ## N
@@ -215,53 +227,48 @@
 #ifndef __ASSEMBLER__
 
 
-/** \name IO register bit manipulation */
-
-/*@{*/
-
-
-
-/** \def bit_is_set
-    \ingroup avr_sfr
-
-    \code #include <avr/io.h>\endcode
-
-    Test whether bit \c bit in IO register \c sfr is set. 
-    This will return a 0 if the bit is clear, and non-zero
-    if the bit is set. */
+/**
+ * @name IO Register Bit Manipulation
+ *
+ * @{
+ */
 
+/**
+ * @code #include <avr/io.h> @endcode
+ *
+ * Test whether bit @c bit in IO register @c sfr is set.
+ * This will return a 0 if the bit is clear, and non-zero
+ * if the bit is set.
+ */
 #define bit_is_set(sfr, bit) (_SFR_BYTE(sfr) & _BV(bit))
 
-/** \def bit_is_clear
-    \ingroup avr_sfr
-
-    \code #include <avr/io.h>\endcode
-
-    Test whether bit \c bit in IO register \c sfr is clear. 
-    This will return non-zero if the bit is clear, and a 0
-    if the bit is set. */
+/**
+ * @code #include <avr/io.h> @endcode
+ *
+ * Test whether bit @c bit in IO register @c sfr is clear.
+ * This will return non-zero if the bit is clear, and a 0
+ * if the bit is set.
+ */
 
 #define bit_is_clear(sfr, bit) (!(_SFR_BYTE(sfr) & _BV(bit)))
 
-/** \def loop_until_bit_is_set
-    \ingroup avr_sfr
-
-    \code #include <avr/io.h>\endcode
-
-    Wait until bit \c bit in IO register \c sfr is set. */
-
+/**
+ * @code #include <avr/io.h> @endcode
+ *
+ * Wait until bit @c bit in IO register @c sfr is set.
+ */
 #define loop_until_bit_is_set(sfr, bit) do { } while (bit_is_clear(sfr, bit))
 
-/** \def loop_until_bit_is_clear
-    \ingroup avr_sfr
-
-    \code #include <avr/io.h>\endcode
-
-    Wait until bit \c bit in IO register \c sfr is clear. */
-
+/**
+ * @code #include <avr/io.h> @endcode
+ *
+ * Wait until bit @c bit in IO register @c sfr is clear.
+ */
 #define loop_until_bit_is_clear(sfr, bit) do { } while (bit_is_set(sfr, bit))
 
-/*@}*/
+/** @} */
+
+/** @} */
 
 #endif /* !__ASSEMBLER__ */