--- a/src/internet-stack/ipv4-end-point-demux.h	Fri Jun 13 15:35:07 2008 +0100
+++ b/src/internet-stack/ipv4-end-point-demux.h	Fri Jun 13 16:47:07 2008 -0400
@@ -30,6 +30,16 @@
 
 class Ipv4EndPoint;
 
+/**
+ * \brief Demultiplexes packets to various transport layer endpoints
+ *
+ * This class serves as a lookup table to match partial or full information
+ * about a four-tuple to an ns3::Ipv4EndPoint.  It internally contains a list
+ * of endpoints, and has APIs to add and find endpoints in this demux.  This
+ * code is shared in common to TCP and UDP protocols in ns3.  This demux
+ * sits between ns3's layer four and the socket layer
+ */
+
 class Ipv4EndPointDemux {
 public:
   typedef std::list<Ipv4EndPoint *> EndPoints;

--- a/src/internet-stack/ipv4-end-point.h	Fri Jun 13 15:35:07 2008 +0100
+++ b/src/internet-stack/ipv4-end-point.h	Fri Jun 13 16:47:07 2008 -0400
@@ -30,6 +30,17 @@
 class Header;
 class Packet;
 
+/**
+ * \brief A representation of an internet endpoint/connection
+ *
+ * This class provides an internet four-tuple (source and destination ports 
+ * and addresses).  These are used in the ns3::Ipv4EndPointDemux as targets
+ * of lookups.  The class also has a callback for notification to higher
+ * layers that a packet from a lower layer was received.  In the ns3
+ * internet-stack, these notifications are automatically registered to be
+ * received by the corresponding socket.
+ */
+
 class Ipv4EndPoint {
 public:
   Ipv4EndPoint (Ipv4Address address, uint16_t port);

--- a/src/internet-stack/ipv4-interface.h	Fri Jun 13 15:35:07 2008 +0100
+++ b/src/internet-stack/ipv4-interface.h	Fri Jun 13 16:47:07 2008 -0400
@@ -58,6 +58,7 @@
  *
  * Subclasses must implement the two methods:
  *   - Ipv4Interface::SendTo
+ *   - Ipv4Interface::GetDevice
  */
 class Ipv4Interface  : public Object
 {

--- a/src/internet-stack/ipv4-l3-protocol.h	Fri Jun 13 15:35:07 2008 +0100
+++ b/src/internet-stack/ipv4-l3-protocol.h	Fri Jun 13 16:47:07 2008 -0400
@@ -43,6 +43,9 @@
 
 /**
  * \brief Implement the Ipv4 layer.
+ * 
+ * This is the actual implementation of IP.  It contains APIs to send and
+ * receive packets at the IP layer, as well as APIs for IP routing.
  */
 class Ipv4L3Protocol : public Object
 {

--- a/src/internet-stack/ipv4-l4-demux.h	Fri Jun 13 15:35:07 2008 +0100
+++ b/src/internet-stack/ipv4-l4-demux.h	Fri Jun 13 16:47:07 2008 -0400
@@ -35,6 +35,9 @@
 
 /**
  * \brief L4 Ipv4 Demux
+ * 
+ * This class demultiplexes IP datagrams to the correct layer four protocol
+ * object.  This demux sits between IP and layer 4.
  */
 class Ipv4L4Demux : public Object
 {

--- a/src/internet-stack/ipv4-l4-protocol.h	Fri Jun 13 15:35:07 2008 +0100
+++ b/src/internet-stack/ipv4-l4-protocol.h	Fri Jun 13 16:47:07 2008 -0400
@@ -33,10 +33,10 @@
 class Ipv4Address;
 
 /**
- * \brief L4 Protocol base class 
+ * \brief L4 Protocol abstract base class 
  *
- * If you want to implement a new L4 protocol, all you have to do is
- * implement a subclass of this base class and add it to an L4Demux.
+ * This is an abstract base class for layer four protocols which use IPv4 as
+ * the network layer.
  */  
 class Ipv4L4Protocol : public Object
 {

--- a/src/internet-stack/pending-data.h	Fri Jun 13 15:35:07 2008 +0100
+++ b/src/internet-stack/pending-data.h	Fri Jun 13 16:47:07 2008 -0400
@@ -32,7 +32,7 @@
 namespace ns3
 {
 class Packet;
-//Doc:ClassXRef
+
 class PendingData {
 public:
   PendingData ();

--- a/src/internet-stack/tcp-header.h	Fri Jun 13 15:35:07 2008 +0100
+++ b/src/internet-stack/tcp-header.h	Fri Jun 13 16:47:07 2008 -0400
@@ -30,6 +30,14 @@
 
 namespace ns3 {
 
+/**
+ * \brief Header for the Transmission Control Protocol
+ *
+ * This class has fields corresponding to those in a network TCP header
+ * (port numbers, sequence and acknowledgement numbers, flags, etc) as well
+ * as methods for serialization to and deserialization from a byte buffer.
+ */
+
 class TcpHeader : public Header 
 {
 public:

--- a/src/internet-stack/tcp-l4-protocol.h	Fri Jun 13 15:35:07 2008 +0100
+++ b/src/internet-stack/tcp-l4-protocol.h	Fri Jun 13 16:47:07 2008 -0400
@@ -39,9 +39,16 @@
 class Node;
 class Socket;
 class TcpHeader;
+
 /**
- * \brief Implementation of the TCP protocol
- */
+ * \brief A layer between the sockets interface and IP
+ * 
+ * This class allocates "endpoint" objects (ns3::Ipv4EndPoint) for TCP,
+ * and SHOULD checksum packets its receives from the socket layer going down
+ * the stack , but currently checksumming is disabled.  It also recieves 
+ * packets from IP, and forwards them up to the endpoints.
+*/
+
 class TcpL4Protocol : public Ipv4L4Protocol {
 public:
   static TypeId GetTypeId (void);

--- a/src/internet-stack/tcp-socket-factory-impl.h	Fri Jun 13 15:35:07 2008 +0100
+++ b/src/internet-stack/tcp-socket-factory-impl.h	Fri Jun 13 16:47:07 2008 -0400
@@ -35,11 +35,13 @@
  * \ingroup Tcp
  * \section Tcp Overview
  *
- * The TCP code in ns3::InternetNode is ported from the  
+ * The TCP code in ns3's internet stack is ported from the  
  * <a href="http://www.ece.gatech.edu/research/labs/MANIACS/GTNetS/">
  * Georgia Tech Network Simulator (GTNetS)</a>.
- * 
+ *
  * Most of the logic is in class ns3::TcpSocketImpl.
+ * This class serves to create sockets of the TcpSocketImpl
+ * type.  That is, it creates sockets which use the GTNetS Tahoe code.
  */
 class TcpSocketFactoryImpl : public TcpSocketFactory
 {

--- a/src/internet-stack/tcp-socket-impl.h	Fri Jun 13 15:35:07 2008 +0100
+++ b/src/internet-stack/tcp-socket-impl.h	Fri Jun 13 16:47:07 2008 -0400
@@ -42,6 +42,20 @@
 class TcpL4Protocol;
 class TcpHeader;
 
+/**
+ * \ingroup socket
+ *
+ * \brief An implementation of a stream socket using TCP.
+ *
+ * This class contains an implementation of TCP Tahoe, as well as a sockets
+ * interface for talking to TCP.  Features include connection orientation,
+ * reliability through cumulative acknowledgements, congestion and flow 
+ * control.  Finite send/receive buffer semantics are modeled.
+ *
+ * Asynchronous callbacks to provide notifications to higher layers that a 
+ * protocol event has occured, such as space freeing up in the send buffer
+ * or new data arriving in the receive buffer.
+ */
 class TcpSocketImpl : public TcpSocket
 {
 public:

--- a/src/internet-stack/udp-header.h	Fri Jun 13 15:35:07 2008 +0100
+++ b/src/internet-stack/udp-header.h	Fri Jun 13 16:47:07 2008 -0400
@@ -29,6 +29,10 @@
 namespace ns3 {
 /**
  * \brief Packet header for UDP packets
+ *
+ * This class has fields corresponding to those in a network UDP header
+ * (port numbers, payload size, checksum) as well as methods for serialization
+ * to and deserialization from a byte buffer.
  */
 class UdpHeader : public Header 
 {

--- a/src/internet-stack/udp-socket-impl.h	Fri Jun 13 15:35:07 2008 +0100
+++ b/src/internet-stack/udp-socket-impl.h	Fri Jun 13 16:47:07 2008 -0400
@@ -36,6 +36,13 @@
 class Packet;
 class UdpL4Protocol;
 
+/**
+ * \brief A sockets interface to UDP
+ * 
+ * This class subclasses ns3::UdpSocket, and provides a socket interface
+ * to ns3's implementation of UDP.
+ */
+
 class UdpSocketImpl : public UdpSocket
 {
 public: