--- a/src/devices/csma/csma-net-device.cc	Wed Dec 10 13:28:51 2008 +0100
+++ b/src/devices/csma/csma-net-device.cc	Wed Dec 10 21:11:05 2008 -0800
@@ -83,10 +83,10 @@
                    MakePointerAccessor (&CsmaNetDevice::m_queue),
                    MakePointerChecker<Queue> ())
     .AddTraceSource ("Rx", 
-                     "The trace source to fire on reception of a MAC packet.",
+                     "Trace source indicating reception of packet destined for broadcast, multicast or local address.",
                      MakeTraceSourceAccessor (&CsmaNetDevice::m_rxTrace))
     .AddTraceSource ("Drop", 
-                     "Trace source to fire on when a MAC packet is dropped.",
+                     "Trace source indicating packet discarded due to receiver disabled or error model decision.",
                      MakeTraceSourceAccessor (&CsmaNetDevice::m_dropTrace))
     ;
   return tid;

--- a/src/devices/csma/csma.h	Wed Dec 10 13:28:51 2008 +0100
+++ b/src/devices/csma/csma.h	Wed Dec 10 21:11:05 2008 -0800
@@ -23,7 +23,7 @@
  * There are a number of conventions in use for describing layered 
  * communications architectures in the literature and in textbooks.  The most
  * common layering  model is the ISO seven layer reference model.  In this view
- * the CsmaNetDevice and CsmaChannel pair occupies the lowest two 
+ * the ns3::CsmaNetDevice and ns3::CsmaChannel pair occupies the lowest two 
  * layers -- at the physical (layer one), and data link (layer two) positions.
  * Another important reference model is that specified by RFC 1122, 
  * "Requirements for Internet Hosts -- Communication Layers."  In this view the
@@ -43,7 +43,7 @@
  *
  * The "top" of the CSMA device defines the transition from the network layer
  * to the data link layer.  This transition is performed by higher layers by 
- * calling either CsmaNetDevice::Send or CsmaNetDevice::SendFrom.
+ * calling either ns3::CsmaNetDevice::Send or ns3::CsmaNetDevice::SendFrom.
  *
  * In contrast to the IEEE 802.3 standards, there is no precisely specified
  * PHY in the CSMA model in the sense of wire types, signals or pinouts.  The
@@ -55,25 +55,25 @@
  *
  * The CsmaNetDevice calls the CsmaChannel through a media independent
  * interface.  There is a method defined to tell the channel when to start 
- * "wiggling the wires" using the method CsmaChannel::TransmitStart, and 
+ * "wiggling the wires" using the method ns3::CsmaChannel::TransmitStart, and 
  * a method to tell the channel when the transmission process is done and
  * the channel should begin propagating the last bit across the "wire":
- * CsmaChannel::TransmitEnd.
+ * ns3::CsmaChannel::TransmitEnd.
  *
  * When the TransmitEnd method is executed, the channel will model a single 
  * uniform signal propagation delay in the medium and deliver copes of the packet
  * to each of the devices attached to the packet via the 
- * CsmaNetDevice::Receive method.
+ * ns3::CsmaNetDevice::Receive method.
  *
  * There is a "pin" in the device media independent interface corresponding to 
  * "COL" (collision).  The state of the channel may be sensed by calling 
- * CsmaChannel::GetState.  Each device will look at this "pin" before 
+ * ns3::CsmaChannel::GetState.  Each device will look at this "pin" before 
  * starting a send and will perform appropriate backoff operations if required.
  *
  * Properly received packets are forwarded up to higher levels from the 
  * CsmaNetDevice via a callback mechanism.  The callback function is
  * initialized by the higher layer (when the net device is attached) using
- * CsmaNetDevice::SetReceiveCallback and is invoked upon "proper"
+ * ns3::CsmaNetDevice::SetReceiveCallback and is invoked upon "proper"
  *  reception of a packet by the net device in order to forward the packet up
  * the protocol stack.
  *
@@ -116,9 +116,9 @@
  * the wire to the "far end."  
  *
  * The transition to the TRANSMITTING state is  driven by a call to 
- * CsmaChannel::TransmitStart which is called by the net device that 
+ * ns3::CsmaChannel::TransmitStart which is called by the net device that 
  * transmits the packet.  It is the responsibility of that device to end the
- * transmission with a call to CsmaChannel::TransmitEnd at the appropriate
+ * transmission with a call to ns3::CsmaChannel::TransmitEnd at the appropriate
  * simulation time that reflects the time elapsed to put all of the packet bits
  * on the wire.  When TransmitEnd is called, the channel schedules an event
  * corresponding to a single speed-of-light delay.  This delay applies to all
@@ -199,7 +199,7 @@
  * the device MAC hooks.
  *
  * When a packet is sent to the CSMA net device for transmission it always 
- * passed through the transmit queue.  The transmit queue in the 
+ * passes through the transmit queue.  The transmit queue in the 
  * CsmaNetDevice inherits from Queue, and therefore inherits three 
  * trace sources:
  *
@@ -211,8 +211,8 @@
  * exactly these three trace sources on the single transmit queue of the device.  
  *
  * The m_traceEnqueue event is triggered when a packet is placed on the transmit
- * queue.  This happens at the time that CsmaNetDevice::Send or 
- * CsmaNetDevice::SendFrom is called by a higher layer to queue a packet for 
+ * queue.  This happens at the time that ns3::CsmaNetDevice::Send or 
+ * ns3::CsmaNetDevice::SendFrom is called by a higher layer to queue a packet for 
  * transmission.
  *
  * The m_traceDequeue event is triggered when a packet is removed from the
@@ -244,16 +244,16 @@
 
  * The trace source m_dropTrace is called to indicate a packet that is dropped
  * by the device.  This happens in two cases:  First, if the receive side of 
- * the net device is not enabled (see CsmaNetDevice::m_receiveEnable and the 
+ * the net device is not enabled (see ns3::CsmaNetDevice::m_receiveEnable and the 
  * associated attribute "ReceiveEnable").
  *
  * The m_dropTrace is also used to indicate that a packet was discarded as 
  * corrupt if a receive error model is used (see 
- * CsmaNetDevice::m_receiveErrorModel and the associated attribute 
+ * ns3::CsmaNetDevice::m_receiveErrorModel and the associated attribute 
  * "ReceiveErrorModel").
  *
  * The other low-level trace source fires on reception of an accepted packet
- * (see CsmaNetDevice::m_rxTrace).  A packet is accepted if it is destined
+ * (see ns3::CsmaNetDevice::m_rxTrace).  A packet is accepted if it is destined
  * for the broadcast address, a multicast address, or to the MAC address 
  * assigned to the net device.
  *

--- a/src/devices/emu/emu.h	Wed Dec 10 13:28:51 2008 +0100
+++ b/src/devices/emu/emu.h	Wed Dec 10 21:11:05 2008 -0800
@@ -1,8 +1,8 @@
 /**
  * \ingroup devices
- * \defgroup Emulated Emulated Net Device Model
+ * \defgroup EmuModel Emulated Net Device Model
  *
- * \section Emulated Net Device Model
+ * \section EmuModelOverview Emulated Net Device Model Overview
  *
  * The emulated net device allows a simulation node to send and receive packets
  * a real network.
@@ -57,4 +57,58 @@
  * implication this has for static global routing.  The global router module
  * attempts to walk the channels looking for adjacent networks.  Since there 
  * is no channel, the global router will be unable to do this.
+ *
+ * \section EmuTracingModel Emulated Net Device Tracing Model
+ *
+ * Like all ns-3 devices, the Emu Model provides a number of trace sources.
+ * These trace sources can be hooked using your own custom trace code, or you
+ * can use our helper functions to arrange for tracing to be enabled on devices
+ * you specify.
+ *
+ * \subsection EmuTracingModelUpperHooks Upper-Level (MAC) Hooks
+ *
+ * From the point of view of tracing in the net device, there are several 
+ * interesting points to insert trace hooks.  A convention inherited from other
+ * simulators is that packets destined for transmission onto attached networks
+ * pass through a single "transmit queue" in the net device.  We provide trace 
+ * hooks at this point in packet flow, which corresponds (abstractly) only to a 
+ * transition from the network to data link layer, and call them collectively
+ * the device MAC hooks.
+ *
+ * When a packet is sent to the Emu net device for transmission it always 
+ * passes through the transmit queue.  The transmit queue in the EmuNetDevice
+ * inherits from Queue, and therefore inherits three trace sources:
+ *
+ * - An Enqueue operation source (see Queue::m_traceEnqueue);
+ * - A Dequeue operation source (see Queue::m_traceDequeue);
+ * - A Drop operation source (see Queue::m_traceDrop).
+ *
+ * The upper-level (MAC) trace hooks for the EmuNetDevice are, in fact, 
+ * exactly these three trace sources on the single transmit queue of the device.  
+ *
+ * The m_traceEnqueue event is triggered when a packet is placed on the transmit
+ * queue.  This happens at the time that ns3::EmuNetDevice::Send or 
+ * ns3::EmuNetDevice::SendFrom is called by a higher layer to queue a packet for 
+ * transmission.
+ *
+ * The m_traceDequeue event is triggered when a packet is removed from the
+ * transmit queue.  Dequeues from the transmit queue happen immediately after
+ * the packet was enqueued and only indicate that the packet is about to be
+ * sent to an underlying raw socket.  The actual time at which the packet is
+ * sent out on the wire is not available.
+ *
+ * \subsection EmuTracingModelUpperHooks Lower-Level (PHY) Hooks
+ *
+ * Similar to the upper level trace hooks, there are trace hooks available at
+ * the lower levels of the net device.  We call these the PHY hooks.  These 
+ * events fire from the device methods that talk directly to the underlying
+ * raw socket.
+ *
+ * The trace source m_dropTrace is not used in the Emu net device since that
+ * is really the business of the underlying "real" device driver.
+ *
+ * The other low-level trace source fires on reception of an accepted packet
+ * (see ns3::EmuNetDevice::m_rxTrace).  A packet is accepted if it is destined
+ * for the broadcast address, a multicast address, or to the MAC address 
+ * assigned to the Emu net device.
  */

--- a/src/devices/point-to-point/point-to-point-net-device.cc	Wed Dec 10 13:28:51 2008 +0100
+++ b/src/devices/point-to-point/point-to-point-net-device.cc	Wed Dec 10 21:11:05 2008 -0800
@@ -73,11 +73,10 @@
                    MakeTimeAccessor (&PointToPointNetDevice::m_tInterframeGap),
                    MakeTimeChecker ())
     .AddTraceSource ("Rx", 
-                     "Trace source to fire on reception of a MAC packet.",
+                     "Trace source indicating reception of packet from the PointToPointChannel.",
                      MakeTraceSourceAccessor (&PointToPointNetDevice::m_rxTrace))
     .AddTraceSource ("Drop",
-                     "Trace source to fire on when a MAC packet is dropped.",
-
+                     "Trace source indicating a packet was discarded due to a ReceiveErrorModel decision.",
                      MakeTraceSourceAccessor (&PointToPointNetDevice::m_dropTrace))
 
     ;

--- a/src/devices/point-to-point/point-to-point.h	Wed Dec 10 13:28:51 2008 +0100
+++ b/src/devices/point-to-point/point-to-point.h	Wed Dec 10 21:11:05 2008 -0800
@@ -1,8 +1,8 @@
 /**
  * \ingroup devices
- * \defgroup PointToPoint Point-to-Point Model
+ * \defgroup PointToPointModel Point-to-Point Model
  *
- * \section Point-to-Point Model
+ * \section PointToPointPointOverview Point-to-Point Model Overview
  *
  * The ns-3 point-to-point model is of a very simple point to point data link
  * connecting exactly two ns3::PointToPointNetDevice devices over an
@@ -21,17 +21,17 @@
  * for IP Version 4 which is the sixteen-bit number 0x21 (see
  * http://www.iana.org/assignments/ppp-numbers).
  *
- * The ns3::PointToPointNetDevice provides following Attributes:
+ * The PointToPointNetDevice provides following Attributes:
  *
  * - Address:       The ns3::Mac48Address of the device (if desired);
- * - DataRate:      The data rate of the device;
- * - TxQueue:       The trasmit queue used by the device;
- * - InterframeGap: The optional time to wait between "frames";
+ * - DataRate:      The data rate (ns3::DataRate) of the device;
+ * - TxQueue:       The trasmit queue (ns3::Queue) used by the device;
+ * - InterframeGap: The optional ns3::Time to wait between "frames";
  * - Rx:            A trace source for received packets;
  * - Drop:          A trace source for dropped packets.
  *
- * The ns3::PointToPointNetDevice models a transmitter section that puts bits
- * on a corresponding channel "wire."  THe DataRate attribute specifies the
+ * The PointToPointNetDevice models a transmitter section that puts bits
+ * on a corresponding channel "wire."  `The DataRate attribute specifies the
  * number of bits per second that the device will simulate sending over the 
  * channel.  In reality no bits are sent, but an event is scheduled for an
  * elapsed time consistent with the number of bits in each packet and the 
@@ -39,21 +39,95 @@
  * models a receiver section that can receive any any data rate.  Therefore
  * there is no need, nor way to set a receive data rate in this model.  By
  * setting the DataRate on the transmitter of both devices connected to a 
- * given ns3::PointToPointChannel one can model a symmetric channel; or by 
+ * given PointToPointChannel one can model a symmetric channel; or by 
  * setting different DataRates one can model an asymmetric channel (e.g., 
  * ADSL).
  *
- * The ns3::PointToPointNetDevice supports the assignment of a "receive error 
+ * The PointToPointNetDevice supports the assignment of a "receive error 
  * model."  This is an ns3::ErrorModel object that is used to simulate data
  * corruption on the link.
  *
+ * \section PointToPointChannelModel Point-to-Point Channel Model
+
  * The point to point net devices are connected via an 
  * ns3::PointToPointChannel.  This channel models two wires transmitting bits
  * at the data rate specified by the source net device.  There is no overhead
  * beyond the eight bits per byte of the packet sent.  That is, we do not 
  * model Flag Sequences, Frame Check Sequences nor do we "escape" any data.
  *
- * The ns3::PointToPointNetChannel provides following Attributes:
+ * The PointToPointNetChannel provides following Attributes:
+ *
+ * - Delay:  An ns3::Time specifying the speed of light transmission delay for
+ *   the channel.
+ *
+ * \section PointToPointTracingModel Point-to-Point Tracing Model
+ *
+ * Like all ns-3 devices, the Point-to-Point Model provides a number of trace 
+ * sources.  These trace sources can be hooked using your own custom trace code,
+ * or you can use our helper functions to arrange for tracing to be enabled on 
+ * devices you specify.
+ *
+ * \subsection PointToPointTracingModelUpperHooks Upper-Level (MAC) Hooks
+ *
+ * From the point of view of tracing in the net device, there are several 
+ * interesting points to insert trace hooks.  A convention inherited from other
+ * simulators is that packets destined for transmission onto attached networks
+ * pass through a single "transmit queue" in the net device.  We provide trace 
+ * hooks at this point in packet flow, which corresponds (abstractly) only to a 
+ * transition from the network to data link layer, and call them collectively
+ * the device MAC hooks.
+ *
+ * When a packet is sent to the Point-to-Point net device for transmission it 
+ * always passes through the transmit queue.  The transmit queue in the 
+ * PoiintToPointNetDevice inherits from Queue, and therefore inherits three 
+ * trace sources:
+ *
+ * - An Enqueue operation source (see Queue::m_traceEnqueue);
+ * - A Dequeue operation source (see Queue::m_traceDequeue);
+ * - A Drop operation source (see Queue::m_traceDrop).
+ *
+ * The upper-level (MAC) trace hooks for the PointToPointNetDevice are, in fact, 
+ * exactly these three trace sources on the single transmit queue of the device.  
  *
- * - Delay:       The speed of light transmission delay for the channel.
+ * The m_traceEnqueue event is triggered when a packet is placed on the transmit
+ * queue.  This happens at the time that ns3::PointtoPointNetDevice::Send or 
+ * ns3::PointToPointNetDevice::SendFrom is called by a higher layer to queue a 
+ * packet for transmission.  An Enqueue trace event firing should be interpreted
+ * as only indicating that a higher level protocol has sent a packet to the device.
+ *
+ * The m_traceDequeue event is triggered when a packet is removed from the
+ * transmit queue.  Dequeues from the transmit queue can happen in two
+ * situations:  1) If the underlying channel is idle when 
+ * PointToPointNetDevice::Send is called, a packet is dequeued from the transmit
+ * queue and immediately transmitted;  2) a packet may be dequeued and 
+ * immediately transmitted in an internal TransmitCompleteEvent that functions 
+ * much  like a transmit complete interrupt service routine.  An Dequeue trace 
+ * event firing may be viewed as indicating that the PointToPointNetDevice has
+ * begun transmitting a packet.
+ *
+ * \subsection CsmaTracingModelUpperHooks Lower-Level (PHY) Hooks
+ *
+ * Similar to the upper level trace hooks, there are trace hooks available at
+ * the lower levels of the net device.  We call these the PHY hooks.  These 
+ * events fire from the device methods that talk directly to the 
+ * PointToPointChannel.
+
+ * The trace source m_dropTrace is called to indicate a packet that is dropped
+ * by the device.  This happens when a packet is discarded as corrupt due to a 
+ * receive error model indication (see ns3::ErrorModel and the associated 
+ * attribute "ReceiveErrorModel").
+ *
+ * The other low-level trace source fires on reception of a packet (see 
+ * ns3::PointToPointNetDevice::m_rxTrace) from the PointToPointChannel.
+ *
+ * \section PointToPointModelSummary Point-To-Point Model Summary
+ *
+ * The ns3 Point-to-Point model is a simplistic model of a point to point
+ * serial line link.
+ *
+ * Ns-3 Attributes provide a mechanism for setting various parameters in the 
+ * device and channel such as data rates, speed-of-light delays and error model
+ * selection.  Trace hooks are provided in the usual manner with a set of 
+ * upper level hooks corresponding to a transmit queue and used in ASCII 
+ * tracing; and also a set of lower level hooks used in pcap tracing.
  */

--- a/src/devices/wifi/wifi.h	Wed Dec 10 13:28:51 2008 +0100
+++ b/src/devices/wifi/wifi.h	Wed Dec 10 21:11:05 2008 -0800
@@ -2,7 +2,7 @@
  * \ingroup devices
  * \defgroup Wifi Wifi Models
  *
- * \section Wifi Models
+ * \section WifiModelOverview Wifi Models Overview
  *
  * The set of 802.11 models provided in ns-3 attempts to provide
  * an accurate MAC-level implementation of the 802.11 specification
@@ -15,7 +15,6 @@
  *   - the so-called MAC high models: they implement the MAC-level
  *     beacon generation, probing, and association state machines.
  *   - a set of Rate control algorithms used by the MAC low models.
- * 
  *
  * We have today 3 MAC high models:
  *   - a simple adhoc state machine which does not perform any
@@ -49,7 +48,61 @@
  *   - ns3::OnoeMacStations
  *   - ns3::AmrrMacStations
  *
- * \section Wifi Tutorial
+ * \section WifiTracingModel Wifi Tracing Model
+ *
+ * Like all ns-3 devices, the Wifi Model provides a number of trace sources.
+ * These trace sources can be hooked using your own custom trace code, or you
+ * can use our helper functions to arrange for tracing to be enabled on devices
+ * you specify.
+ *
+ * \subsection WifiTracingModelUpperHooks Upper-Level (MAC) Hooks
+ *
+ * From the point of view of tracing in the net device, there are several 
+ * interesting points to insert trace hooks.  The first is at the interface
+ * between the device and higher layers.  We provide trace hooks at this point
+ * in packet flow, which corresponds to a transition from the network to data 
+ * link layer, and call them collectively the device MAC hooks.
+ *
+ * The first trace hook is called "Rx" and is fired using the 
+ * ns3::WifiNetDevice::m_rxLogger trace hook.  The perspective here is looking
+ * down into the WifiNetDevice so a receive indicates a packet being sent up
+ * from the channel to be forwarded up to higher layers.
+ *
+ * The second trace hook is called "Tx" and is fired using the 
+ * ns3::WifiNetDevice::m_txLogger trace hook.  This trace hook indicates a 
+ * packet has been sent from higher layers down to the net device for 
+ * transmission onto the network.
+ *
+ * \subsection WifiTracingModelLowerHooks Low-Level (PHY) Hooks
  *
+ * Another interesting place to insert trace hooks is in the state machine
+ * that is driving the actual device transmission and reception logic.  We 
+ * provide the following hooks to instrument the lower levels of the device.
  *
+ * First, we provide a trace hook to indicate state changes.  This trace
+ * source is called "State" and is fired using the 
+ * ns3::WifiPhyStateHelper::m_stateLogger trace source.
+ *
+ * We also provide a trace hook to indicate the successful reception of a
+ * packet from the channel.  This trace source is called "RxOk" and is 
+ * accessed using the ns3::WifiPhyStateHelper::m_rxOkTrace trace source.
+ *
+ * There also exists a trace hook to indicate an unsuccessful reception of a
+ * packet from the channel.  This trace source is called "RxError" and is 
+ * accessed using the ns3::WifiPhyStateHelper::m_rxErrorTrace trace source.
+ *
+ * There is a trace hook to indicate that transmission of a packet is 
+ * starting onto the channel.  This trace source is called "Tx" (don't 
+ * confuse it with the higher layer "Tx" hook) and is 
+ * fired using the ns3::WifiPhyStateHelper::m_txTrace trace source.
+ *
+ * \subsection WifiTracingModelRemoteHooks Remote Station Hooks
+ *
+ * We provide access to changes in the the per-remote-station RTS counter 
+ * through the "Ssrc" trace source which is fired using the 
+ *  ns3::WifiRemoteStation::m_ssrc trace hook.
+ * 
+ * Finally, we provide access to the per-remote-station SLRC couter that
+ * indications the number of retransmissions of data.  Changes to this 
+ * counter are traced using the ns3::WifiRemoteStation::m_slrc source.
  */