Diff: SocketAddress.h

Revision:

104:d28d8b508e7c

Parent:

94:644df37bb05b

Child:

105:2fd212f8da61

--- a/SocketAddress.h	Tue Apr 19 18:26:12 2016 -0500
+++ b/SocketAddress.h	Tue Apr 19 18:26:21 2016 -0500
@@ -1,4 +1,4 @@
-/* Socket
+/* SocketAddress
  * Copyright (c) 2015 ARM Limited
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
@@ -28,8 +28,11 @@
  */
 #define NSAPI_IP_BYTES NSAPI_IPv6_BYTES
 
-/** Enum of address families
- *  @enum nsapi_family_t
+/** Enum of IP address versions
+ *
+ *  The IP version specifies the type of an IP address.
+ *
+ *  @enum nsapi_version_t
  */
 enum nsapi_version_t {
     NSAPI_IPv4, /*!< Address is IPv4 */
@@ -56,74 +59,92 @@
 class NetworkInterface;
 
 
-/** A general address class composed of the IP address and optional port
+/** SocketAddress class
+ *
+ *  Representation of an IP address and port pair. 
  */
 class SocketAddress {
 public:
-    /** SocketAddress construction using DNS resolution
-     *  @param iface    NetworkInterface to use for DNS resolution
-     *  @param addr     Null-terminated hostname that will be resolved
+    /** Create a SocketAddress from a hostname and port
+     *
+     *  The hostname may be either a domain name or an IP address. If the
+     *  hostname is an IP address, no network transactions will be performed.
+     *
+     *  On failure, the IP address and port will be set to zero
+     *  
+     *  @param iface    Network stack to use for DNS resolution
+     *  @param host     Hostname to resolve
      *  @param port     Optional 16-bit port
-     *  @note on failure, IP address and port will be set to zero
      */
-    SocketAddress(NetworkInterface *iface, const char *addr, uint16_t port = 0);
+    SocketAddress(NetworkInterface *iface, const char *host, uint16_t port = 0);
 
-    /** SocketAddress construction
-     *  @param addr     Null-terminated IP address
+    /** Create a SocketAddress from an IP address and port
+     *
+     *  @param host     Null-terminated representation of the IP address
      *  @param port     Optional 16-bit port
      */
     SocketAddress(const char *addr = 0, uint16_t port = 0);
 
-    /** SocketAddress construction
-     *  @param bytes    Bytes to assign to address in big-endian order
+    /** Create a SocketAddress from a raw IP address and port
+     *
+     *  @param bytes    Raw IP address in big-endian order
      *  @param version  IP address version, NSAPI_IPv4 or NSAPI_IPv6
      *  @param port     Optional 16-bit port
      */
     SocketAddress(const void *bytes, nsapi_version_t version, uint16_t port = 0);
 
-    /** SocketAddress construction
-     *  @param addr     SocketAddress to copy
+    /** Create a SocketAddress from another SocketAddress
+     *
+     *  @param address  SocketAddress to copy
      */
     SocketAddress(const SocketAddress &addr);
    
     /** Set the IP address
-     *  @param addr     Null-terminated string representing the IP address
+     *
+     *  @param addr     Null-terminated represention of the IP address
      */
     void set_ip_address(const char *addr);
 
-    /** Set the IP address bytes directly
-     *  @param bytes    Bytes to assign to address in big-endian order
+    /** Set the raw IP address
+     *
+     *  @param bytes    Raw IP address in big-endian order
      *  @param version  IP address version, NSAPI_IPv4 or NSAPI_IPv6
      */
     void set_ip_bytes(const void *bytes, nsapi_version_t version);
 
     /** Set the port
+     *
      *  @param port     16-bit port
      */
     void set_port(uint16_t port);
     
     /** Get the IP address
-     *  @return         The string representation of the IP Address
+     *
+     *  @return         Null-terminated representation of the IP Address
      */
     const char *get_ip_address() const;
 
-    /** Get the IP address bytes directly
-     *  @return         IP address bytes
+    /** Get the raw IP address
+     *
+     *  @return         Raw IP address in big-endian order
      */
     const void *get_ip_bytes() const;
 
-    /** Get the type of the IP address
+    /** Get the IP address version
+     *
      *  @return         IP address version, NSAPI_IPv4 or NSAPI_IPv6
      */
     nsapi_version_t get_ip_version() const;
     
     /** Get the port
+     *
      *  @return         The 16-bit port
      */
     uint16_t get_port() const;
 
-    /** Determine if address is all zeros
-     *  @return         True if address is not zero address
+    /** Test if address is zero
+     *
+     *  @return         True if address is not zero
      */
     operator bool() const;