--- a/src/devices/wifi/mac-high-adhoc.h	Mon Dec 17 13:27:22 2007 +0100
+++ b/src/devices/wifi/mac-high-adhoc.h	Mon Dec 17 13:41:51 2007 +0100
@@ -33,6 +33,13 @@
 class MacStations;
 class WifiPhy;
 
+/**
+ * \brief the Adhoc state machine
+ *
+ * For now, this class is really empty but it should contain
+ * the code for the distributed generation of beacons in an adhoc 
+ * network.
+ */
 class MacHighAdhoc {
 public:
   typedef Callback<void, Ptr<Packet>, const Mac48Address &> ForwardCallback;

--- a/src/devices/wifi/mac-high-nqap.h	Mon Dec 17 13:27:22 2007 +0100
+++ b/src/devices/wifi/mac-high-nqap.h	Mon Dec 17 13:41:51 2007 +0100
@@ -35,6 +35,18 @@
 class MacStations;
 class WifiPhy;
 
+/**
+ * \brief non-QoS AP state machine
+ *
+ * Handle association, dis-association and authentication,
+ * of STAs within an IBSS.
+ * This class uses two output queues, each of which is server by
+ * a single DCF
+ *   - the highest priority DCF serves the queue which contains
+ *     only beacons.
+ *   - the lowest priority DCF serves the queue which contains all
+ *     other frames, including user data frames.
+ */
 class MacHighNqap {
 public:
   typedef Callback<void, Ptr<Packet>, const Mac48Address &> ForwardCallback;
@@ -52,6 +64,9 @@
 
   void Queue (Ptr<const Packet> packet, Mac48Address to);
 
+  /**
+   * Start beacon transmission immediately.
+   */
   void StartBeaconing (void);
 
   void Receive (Ptr<Packet> packet, WifiMacHeader const *hdr);

--- a/src/devices/wifi/mac-high-nqsta.h	Mon Dec 17 13:27:22 2007 +0100
+++ b/src/devices/wifi/mac-high-nqsta.h	Mon Dec 17 13:41:51 2007 +0100
@@ -38,6 +38,16 @@
 class WifiPhy;
 class MacStations;
 
+/**
+ * \brief a non-QoS STA state machine
+ *
+ * This state machine handles association, disassociation,
+ * authentication and beacon monitoring. It does not perform
+ * channel scanning.
+ * If the station detects a certain number of missed beacons
+ * while associated, it automatically attempts a new association
+ * sequence.
+ */
 class MacHighNqsta {
 public:
   typedef Callback<void, Ptr<Packet>, const Mac48Address &> ForwardCallback;
@@ -55,12 +65,31 @@
   void SetPhy (Ptr<WifiPhy> phy);
   void SetStations (MacStations *stations);
 
+  /**
+   * \param missed the number of beacons which must be missed
+   * before a new association sequence is started.
+   */
   void SetMaxMissedBeacons (uint32_t missed);
+  /**
+   * \param timeout
+   *
+   * If no probe response is received within the specified
+   * timeout, the station sends a new probe request.
+   */
   void SetProbeRequestTimeout (Time timeout);
+  /**
+   * \param timeout
+   *
+   * If no association response is received within the specified
+   * timeout, the station sends a new association request.
+   */
   void SetAssocRequestTimeout (Time timeout);
 
   Mac48Address GetBssid (void) const;
 
+  /**
+   * Start an active association sequence immediately.
+   */
   void StartActiveAssociation (void);
 
   void Queue (Ptr<const Packet> packet, Mac48Address to);

--- a/src/devices/wifi/wifi.h	Mon Dec 17 13:27:22 2007 +0100
+++ b/src/devices/wifi/wifi.h	Mon Dec 17 13:41:51 2007 +0100
@@ -20,21 +20,23 @@
  *   - a simple adhoc state machine which does not perform any
  *     kind of beacon generation, probing, or association. This
  *     state machine is implemented by the ns3::AdhocWifiNetDevice
- *     class.
+ *     and ns3::MacHighAdhoc classes.
  *   - an active probing and association state machine which handles
  *     automatic re-association whenever too many beacons are missed
- *     is implemented by the ns3::NqstaWifiNetDevice class.
+ *     is implemented by the ns3::NqstaWifiNetDevice and 
+ *     ns3::MacHighNqsta classes.
  *   - an access point which generates periodic beacons, and which
  *     accepts every attempt to associate. This AP state machine
- *     is implemented by the ns3::NqapWifiNetDevice.
+ *     is implemented by the ns3::NqapWifiNetDevice and 
+ *     ns3::MacHighNqap classes.
  *
  * The MAC low layer is split in 3 components:
  *   - ns3::MacLow which takes care of RTS/CTS/DATA/ACK transactions.
- *   - ns3::Dcf which implements the DCF function.
+ *   - ns3::DcfManager and ns3::DcfState which implements the DCF function.
  *   - ns3::DcaTxop which handles the packet queue, packet fragmentation,
  *     and packet retransmissions if they are needed.
  *
- * The PHY layer implements a single model in ns3::WifiPhy.
+ * The PHY layer implements a single model in the ns3::WifiPhy class.
  *
  * It also provides a set of Rate control algorithms:
  *   - ns3::ArfMacStations (initialized from \valueref{WifiArfTimerThreshold}, and,
@@ -45,6 +47,8 @@
  *   - ns3::IdealMacStations (initialized from \valueref{WifiIdealRateControlBerThreshold})
  *   - ns3::CrMacStations (initialized from \valueref{WifiConstantDataRate}, and,
  *     \valueref{WifiConstantCtlRate}).
+ *   - ns3::OnoeMacStations
+ *   - ns3::AmrrMacStations
  *
  * The type of rate control algorithm is controlled through \valueref{WifiRateControlAlgorithm}.
  *