diff --git a/src/node/address.cc b/src/node/address.cc
index 408a152e6..9bb67f4fb 100644
--- a/src/node/address.cc
+++ b/src/node/address.cc
@@ -47,7 +47,7 @@ Address::GetLength (void) const
   return m_len;
 }
 void 
-Address::CopyTo (uint8_t *buffer) const
+Address::CopyTo (uint8_t buffer[MAX_SIZE]) const
 {
   NS_ASSERT (m_len <= MAX_SIZE);
   memcpy (buffer, m_data, m_len);
diff --git a/src/node/address.h b/src/node/address.h
index 417bdce0a..e6bbec026 100644
--- a/src/node/address.h
+++ b/src/node/address.h
@@ -6,24 +6,116 @@
 
 namespace ns3 {
 
+/**
+ * \brief a polymophic address class
+ *
+ * This class is very similar in design and spirit to the BSD sockaddr
+ * structure: they are both used to hold multiple types of addresses
+ * together with the type of the address.
+ *
+ * A new address class defined by a user needs to:
+ *   - allocate a type id with Address::Register
+ *   - provide a method to convert his new address to an Address 
+ *     instance. This method is typically a member method named ConvertTo:
+ *     Address MyAddress::ConvertTo (void) const;
+ *   - provide a method to convert an Address instance back to
+ *     an instance of his new address type. This method is typically
+ *     a static member method of his address class named ConvertFrom:
+ *     static MyAddress MyAddress::ConvertFrom (const Address &address);
+ *   - the ConvertFrom method is expected to check that the type of the
+ *     input Address instance is compatible with its own type.
+ *
+ * Typical code to create a new class type looks like:
+ * \code
+ * // this class represents addresses which are 2 bytes long.
+ * class MyAddress
+ * {
+ * public:
+ *   Address ConvertTo (void) const;
+ *   static MyAddress ConvertFrom (void);
+ * private:
+ *   static uint8_t GetType (void);
+ * };
+ *
+ * Address MyAddress::ConvertTo (void) const
+ * {
+ *   return Address (GetType (), m_buffer, 2);
+ * }
+ * MyAddress MyAddress::ConvertFrom (const Address &address)
+ * {
+ *   MyAddress ad;
+ *   NS_ASSERT (address.CheckCompatible (GetType (), 2));
+ *   address.CopyTo (ad.m_buffer, 2);
+ *   return ad;
+ * }
+ * uint8_t MyAddress::GetType (void)
+ * {
+ *   static uint8_t type = Address::Register ();
+ *   return type;
+ * }
+ * \endcode
+ */
 class Address 
 {
 public:
   enum {
+    /**
+     * The maximum size of a byte buffer which
+     * can be stored in an Address instance.
+     */
     MAX_SIZE = 14
   };
 
+  /**
+   * Create an invalid address
+   */
   Address ();
+  /**
+   * \param type the type of the Address to create
+   * \param buffer a pointer to a buffer of bytes which hold
+   *        a serialized representation of the address in network
+   *        byte order.
+   * \param len the length of the buffer.
+   * 
+   * Create an address from a type and a buffer. This constructor
+   * is typically invoked from the conversion functions of various
+   * address types when they have to convert themselves to an 
+   * Address instance.
+   */
   Address (uint8_t type, const uint8_t *buffer, uint8_t len);
   Address (const Address & address);
   Address &operator = (const Address &address);
 
+  /**
+   * \returns the length of the underlying address.
+   */
   uint8_t GetLength (void) const;
-  void CopyTo (uint8_t *buffer) const;
+  /**
+   * \param buffer buffer to copy the address bytes to.
+   */
+  void CopyTo (uint8_t buffer[MAX_SIZE]) const;
+  /**
+   * \param buffer pointer to a buffer of bytes which contain
+   *        a serialized representation of the address in network
+   *        byte order.
+   * \param len length of buffer
+   *
+   * Copy the input buffer to the internal buffer of this address 
+   * instance.
+   */
   void CopyFrom (uint8_t *buffer, uint8_t len);
+  /**
+   * \param type a type id as returned by Address::Register
+   * \param len the length associated to this type id.
+   *
+   * \returns true if the type of the address stored internally
+   * is compatible with the requested type, false otherwise.
+   */
   bool CheckCompatible (uint8_t type, uint8_t len) const;
-
-
+  /**
+   * Allocate a new type id for a new type of address.
+   * \returns a new type id.
+   */
   static uint8_t Register (void);
 private:
   friend bool operator == (const Address &a, const Address &b);
diff --git a/src/node/eui48-address.h b/src/node/eui48-address.h
index b051b4c31..d113503db 100644
--- a/src/node/eui48-address.h
+++ b/src/node/eui48-address.h
@@ -7,13 +7,37 @@ namespace ns3 {
 
 class Address;
 
+/**
+ * \brief an EUI-48 address
+ *
+ * This class can contain 48 bit IEEE addresses.
+ */
 class Eui48Address
 {
 public:
   Eui48Address ();
+  /**
+   * \param str a string representing the new Eui48Address
+   *
+   * The format of the string is "xx:xx:xx:xx:xx:xx"
+   */
   Eui48Address (const char *str);
+  /**
+   * \returns a new Address instance
+   *
+   * Convert an instance of this class to a polymorphic Address instance.
+   */
   Address ConvertTo (void) const;
+  /**
+   * \param address a polymorphic address
+   *
+   * Convert a polymorphic address to an Eui48Address instance.
+   * The conversion performs a type check.
+   */
   static Eui48Address ConvertFrom (const Address &address);
+  /**
+   * Allocate a new Eui48Address.
+   */
   static Eui48Address Allocate (void);
 private:
   static uint8_t GetType (void);
diff --git a/src/node/inet-address.h b/src/node/inet-address.h
index 6ba6da5de..577974325 100644
--- a/src/node/inet-address.h
+++ b/src/node/inet-address.h
@@ -7,21 +7,73 @@
 
 namespace ns3 {
 
+
+/**
+ * \brief an Inet address class
+ *
+ * This class is similar to inet_sockaddr in the BSD socket
+ * API. i.e., this class holds an Ipv4Address and a port number
+ * to form an ipv4 transport endpoint.
+ */
 class InetAddress
 {
 public:
+  /**
+   * \param ipv4 the ipv4 address
+   * \param port the port number
+   */
   InetAddress (Ipv4Address ipv4, uint16_t port);
+  /**
+   * \param ipv4 the ipv4 address
+   *
+   * The port number is set to zero by default.
+   */
   InetAddress (Ipv4Address ipv4);
+  /**
+   * \param port the port number
+   *
+   * The ipv4 address is set to the "Any" address by default.
+   */
   InetAddress (uint16_t port);
+  /**
+   * \param ipv4 string which represents an ipv4 address
+   * \param port the port number
+   */
   InetAddress (const char *ipv4, uint16_t port);
+  /**
+   * \param ipv4 string which represents an ipv4 address
+   *
+   * The port number is set to zero.
+   */
   InetAddress (const char *ipv4);
+  /**
+   * \returns the port number
+   */
   uint16_t GetPort (void) const;
+  /**
+   * \returns the ipv4 address
+   */
   Ipv4Address GetIpv4 (void) const;
 
-  void SetPort (uint16_t post);
+  /**
+   * \param port the new port number.
+   */
+  void SetPort (uint16_t port);
+  /**
+   * \param address the new ipv4 address
+   */
   void SetIpv4 (Ipv4Address address);
 
+  /**
+   * \returns an Address instance which represents this
+   * InetAddress instance.
+   */
   Address ConvertTo (void) const;
+  /**
+   * \param address the Address instance to convert from.
+   * \returns an InetAddress which corresponds to the input
+   * Address
+   */
   static InetAddress ConvertFrom (const Address &address);
 private:
   static uint8_t GetType (void);