--- a/src/helper/wifi-helper.h	Wed Dec 10 00:16:30 2008 -0800
+++ b/src/helper/wifi-helper.h	Wed Dec 10 01:33:58 2008 -0800
@@ -32,10 +32,24 @@
 class WifiNetDevice;
 class Node;
 
+/**
+ * \brief create PHY objects
+ *
+ * This base class must be implemented by new PHY implementation which wish to integrate
+ * with the \ref ns3::WifiHelper class.
+ */
 class WifiPhyHelper
 {
 public:
   virtual ~WifiPhyHelper ();
+  /**
+   * \param node the node on which the PHY object will reside
+   * \param device the device within which the PHY object will reside
+   * \returns a new PHY object.
+   *
+   * Subclasses must implement this method to allow the ns3::WifiHelper class
+   * to create PHY objects from ns3::WifiHelper::Install.
+   */
   virtual Ptr<WifiPhy> Create (Ptr<Node> node, Ptr<WifiNetDevice> device) const = 0;
 };
 
@@ -49,8 +63,18 @@
 class WifiHelper
 {
 public:
+  /**
+   * Create a Wifi helper in an empty state: all its parameters
+   * must be set before calling ns3::WifiHelper::Install
+   */
   WifiHelper ();
 
+  /**
+   * \returns a new WifiHelper in a default state
+   *
+   * The default state is defined as being an Adhoc MAC layer with an ARF rate control algorithm
+   * and both objects using their default attribute values.
+   */
   static WifiHelper Default (void);
 
   /**
@@ -117,7 +141,17 @@
                std::string n6 = "", const AttributeValue &v6 = EmptyAttributeValue (),
                std::string n7 = "", const AttributeValue &v7 = EmptyAttributeValue ());
 
+  /**
+   * \param phy the PHY helper to create PHY objects
+   * \param c the set of nodes on which a wifi device must be created
+   * \returns a device container which contains all the devices created by this method.
+   */
   NetDeviceContainer Install (const WifiPhyHelper &phy, NodeContainer c) const;
+  /**
+   * \param phy the PHY helper to create PHY objects
+   * \param node the node on which a wifi device must be created
+   * \returns a device container which contains all the devices created by this method.
+   */
   NetDeviceContainer Install (const WifiPhyHelper &phy, Ptr<Node> node) const;
 
 private:

--- a/src/helper/yans-wifi-helper.h	Wed Dec 10 00:16:30 2008 -0800
+++ b/src/helper/yans-wifi-helper.h	Wed Dec 10 01:33:58 2008 -0800
@@ -17,21 +17,61 @@
  *
  * Author: Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
  */
-#ifndef YANS_WIFI_PHY_HELPER_H
-#define YANS_WIFI_PHY_HELPER_H
+#ifndef YANS_WIFI_HELPER_H
+#define YANS_WIFI_HELPER_H
 
 #include "wifi-helper.h"
 #include "ns3/yans-wifi-channel.h"
 
 namespace ns3 {
 
+/**
+ * \brief manage and create wifi channel objects for the yans model.
+ *
+ * The intent of this class is to make it easy to create a channel object
+ * which implements the yans channel model. The yans channel model is described
+ * in "Yet Another Network Simulator", http://cutebugs.net/files/wns2-yans.pdf
+ */
 class YansWifiChannelHelper
 {
 public:
+  /**
+   * Create a channel helper without any parameter set. The user must set
+   * them all to be able to call Create later.
+   */
   YansWifiChannelHelper ();
 
+  /**
+   * Create a channel helper in a default working state. By default, we create
+   * a channel model with a propagation delay equal to a constant, the speed of light,
+   * and a propagation loss based on a log distance model with a reference loss of 46.6777 dB
+   * at reference distance of 1m.
+   */
   static YansWifiChannelHelper Default (void);
 
+  /**
+   * \param name the name of the model to add
+   * \param n0 the name of the attribute to set
+   * \param v0 the value of the attribute to set
+   * \param n1 the name of the attribute to set
+   * \param v1 the value of the attribute to set
+   * \param n2 the name of the attribute to set
+   * \param v2 the value of the attribute to set
+   * \param n3 the name of the attribute to set
+   * \param v3 the value of the attribute to set
+   * \param n4 the name of the attribute to set
+   * \param v4 the value of the attribute to set
+   * \param n5 the name of the attribute to set
+   * \param v5 the value of the attribute to set
+   * \param n6 the name of the attribute to set
+   * \param v6 the value of the attribute to set
+   * \param n7 the name of the attribute to set
+   * \param v7 the value of the attribute to set
+   *
+   * Add a propagation loss model to the set of currently-configured loss models.
+   * This method is additive to allow you to construct complex propagation loss models
+   * such as a log distance + jakes model, etc.
+   */
   void AddPropagationLoss (std::string name,
 			   std::string n0 = "", const AttributeValue &v0 = EmptyAttributeValue (),
 			   std::string n1 = "", const AttributeValue &v1 = EmptyAttributeValue (),
@@ -41,6 +81,27 @@
 			   std::string n5 = "", const AttributeValue &v5 = EmptyAttributeValue (),
 			   std::string n6 = "", const AttributeValue &v6 = EmptyAttributeValue (),
 			   std::string n7 = "", const AttributeValue &v7 = EmptyAttributeValue ());
+  /**
+   * \param name the name of the model to set
+   * \param n0 the name of the attribute to set
+   * \param v0 the value of the attribute to set
+   * \param n1 the name of the attribute to set
+   * \param v1 the value of the attribute to set
+   * \param n2 the name of the attribute to set
+   * \param v2 the value of the attribute to set
+   * \param n3 the name of the attribute to set
+   * \param v3 the value of the attribute to set
+   * \param n4 the name of the attribute to set
+   * \param v4 the value of the attribute to set
+   * \param n5 the name of the attribute to set
+   * \param v5 the value of the attribute to set
+   * \param n6 the name of the attribute to set
+   * \param v6 the value of the attribute to set
+   * \param n7 the name of the attribute to set
+   * \param v7 the value of the attribute to set
+   *
+   * Configure a propagation delay for this channel.
+   */
   void SetPropagationDelay (std::string name,
 			    std::string n0 = "", const AttributeValue &v0 = EmptyAttributeValue (),
 			    std::string n1 = "", const AttributeValue &v1 = EmptyAttributeValue (),
@@ -51,6 +112,11 @@
 			    std::string n6 = "", const AttributeValue &v6 = EmptyAttributeValue (),
 			    std::string n7 = "", const AttributeValue &v7 = EmptyAttributeValue ());
 
+  /**
+   * \returns a new channel
+   *
+   * Create a channel based on the configuration parameters set previously.
+   */
   Ptr<YansWifiChannel> Create (void) const;
 
 private:
@@ -58,15 +124,64 @@
   ObjectFactory m_propagationDelay;
 };
 
+/**
+ * \brief Make it easy to create and manager PHY objects for the yans model.
+ *
+ * The yans PHY model is described in "Yet Another Network Simulator", 
+ * http://cutebugs.net/files/wns2-yans.pdf
+ *
+ * The Pcap and ascii traces generated by the EnableAscii and EnablePcap methods defined
+ * in this class correspond to PHY-level traces. That is, they capture traffic
+ * at the top of the PHY layer, just below the MAC layer.
+ */
 class YansWifiPhyHelper : public WifiPhyHelper
 {
 public:
+  /**
+   * Create a phy helper without any parameter set. The user must set
+   * them all to be able to call Install later.
+   */
   YansWifiPhyHelper ();
 
+  /**
+   * Create a phy helper in a default working state.
+   */
   static YansWifiPhyHelper Default (void);
 
+  /**
+   * \param channel the channel to associate to this helper
+   *
+   * Every PHY created by a call to Install is associated to this channel.
+   */
   void SetChannel (Ptr<YansWifiChannel> channel);
+  /**
+   * \param name the name of the attribute to set
+   * \param v the value of the attribute
+   *
+   * Set an attribute of the underlying PHY object.
+   */
   void Set (std::string name, const AttributeValue &v);
+  /**
+   * \param name the name of the error rate model to set.
+   * \param n0 the name of the attribute to set
+   * \param v0 the value of the attribute to set
+   * \param n1 the name of the attribute to set
+   * \param v1 the value of the attribute to set
+   * \param n2 the name of the attribute to set
+   * \param v2 the value of the attribute to set
+   * \param n3 the name of the attribute to set
+   * \param v3 the value of the attribute to set
+   * \param n4 the name of the attribute to set
+   * \param v4 the value of the attribute to set
+   * \param n5 the name of the attribute to set
+   * \param v5 the value of the attribute to set
+   * \param n6 the name of the attribute to set
+   * \param v6 the value of the attribute to set
+   * \param n7 the name of the attribute to set
+   * \param v7 the value of the attribute to set
+   *
+   * Set the error rate model and its attributes to use when Install is called.
+   */
   void SetErrorRateModel (std::string name,
                           std::string n0 = "", const AttributeValue &v0 = EmptyAttributeValue (),
                           std::string n1 = "", const AttributeValue &v1 = EmptyAttributeValue (),
@@ -77,8 +192,6 @@
                           std::string n6 = "", const AttributeValue &v6 = EmptyAttributeValue (),
                           std::string n7 = "", const AttributeValue &v7 = EmptyAttributeValue ());
 
-  virtual Ptr<WifiPhy> Create (Ptr<Node> node, Ptr<WifiNetDevice> device) const;
-
   /**
    * \param filename filename prefix to use for pcap files.
    * \param nodeid the id of the node to generate pcap output for.
@@ -157,6 +270,15 @@
   static void EnableAsciiAll (std::ostream &os);
 
 private:
+  /**
+   * \param node the node on which we wish to create a wifi PHY
+   * \param device the device within which this PHY will be created
+   * \returns a newly-created PHY object.
+   *
+   * This method implements the pure virtual method defined in \ref ns3::WifiPhyHelper.
+   */
+  virtual Ptr<WifiPhy> Create (Ptr<Node> node, Ptr<WifiNetDevice> device) const;
+
   ObjectFactory m_phy;
   ObjectFactory m_errorRateModel;
   Ptr<YansWifiChannel> m_channel;
@@ -164,4 +286,4 @@
 
 } // namespace ns3
 
-#endif /* YANS_WIFI_PHY_HELPER_H */
+#endif /* YANS_WIFI_HELPER_H */