From cb5d18a929dd543ed918d1740b817f67b4b4fd6e Mon Sep 17 00:00:00 2001
From: "Gustavo J. A. M. Carneiro" <gjc@inescporto.pt>
Date: Tue, 26 Aug 2008 12:25:08 +0100
Subject: [PATCH] Bridge documentation (#286)

---
 src/devices/bridge/bridge-channel.h    |  8 +++--
 src/devices/bridge/bridge-net-device.h | 43 ++++++++++++++++++++++++--
 2 files changed, 47 insertions(+), 4 deletions(-)

diff --git a/src/devices/bridge/bridge-channel.h b/src/devices/bridge/bridge-channel.h
index 7a01a821c..34ba227bf 100644
--- a/src/devices/bridge/bridge-channel.h
+++ b/src/devices/bridge/bridge-channel.h
@@ -25,9 +25,13 @@
 namespace ns3 {
 
 /**
- * \ingroup netdevice
+ * \ingroup bridge
  * 
- * \brief bridge net device for bridge things and testing
+ * \brief Virtual channel implementation for bridges (BridgeNetDevice).
+ *
+ * Just like BridgeNetDevice aggregates multiple NetDevices,
+ * BridgeChannel aggregates multiple channels and make them appear as
+ * a single channel to upper layers.
  */
 class BridgeChannel : public Channel
 {
diff --git a/src/devices/bridge/bridge-net-device.h b/src/devices/bridge/bridge-net-device.h
index be44792d6..d4ad8da4e 100644
--- a/src/devices/bridge/bridge-net-device.h
+++ b/src/devices/bridge/bridge-net-device.h
@@ -31,9 +31,37 @@ namespace ns3 {
 class Node;
 
 /**
- * \ingroup netdevice
+ * \ingroup devices
+ * \defgroup bridge Bridge
  * 
- * \brief bridge net device for bridge things and testing
+ * \brief a virtual net device that bridges multiple LAN segments
+ *
+ * The BridgeNetDevice object is a "virtual" netdevice that aggregates
+ * multiple "real" netdevices and implements the data plane forwarding
+ * part of IEEE 802.1D.  By adding a BridgeNetDevice to a Node, it
+ * will act as a "bridge", or "switch", to multiple LAN segments.
+ * 
+ * By default the bridge netdevice implements a "learning bridge"
+ * algorithm (see 802.1D), where incoming unicast frames from one port
+ * may occasionally be forwarded throughout all other ports, but
+ * usually they are forwarded only to a single correct output port.
+ *
+ * \attention The Spanning Tree Protocol part of 802.1D is not
+ * implemented.  Therefore, you have to be careful not to create
+ * bridging loops, or else the network will collapse.
+ *
+ * \attention Bridging is designed to work only with NetDevices
+ * modelling IEEE 802-style technologies, such as CsmaNetDevice and
+ * WifiNetDevice.
+ *
+ * \attention If including a WifiNetDevice in a bridge, the wifi
+ * device must be in Access Point mode.  Adhoc mode is not supported
+ * with bridging.
+ */
+
+/**
+ * \ingroup bridge
+ * \brief a virtual net device that bridges multiple LAN segments
  */
 class BridgeNetDevice : public NetDevice
 {
@@ -41,6 +69,17 @@ public:
   static TypeId GetTypeId (void);
   BridgeNetDevice ();
 
+  /** \brief Add a 'port' to a bridge device
+   *
+   * This method adds a new bridge port to a BridgeNetDevice, so that
+   * the new bridge port NetDevice becomes part of the bridge and L2
+   * frames start being forwarded to/from this NetDevice.
+   *
+   * \attention The netdevice that is being added as bridge port must
+   * _not_ have an IP address.  In order to add IP connectivity to a
+   * bridging node you must enable IP on the BridgeNetDevice itself,
+   * never on its port netdevices.
+   */
   void AddBridgePort (Ptr<NetDevice> bridgePort);
 
   // inherited from NetDevice base class.