Revised documentation for Interface classes

Author: geky

CellularInterface.h

@@ -0,0 +1,45 @@
+/* CellularInterface
+ * Copyright (c) 2015 ARM Limited
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+ 
+#ifndef CELLULAR_INTERFACE_H
+#define CELLULAR_INTERFACE_H
+ 
+#include "NetworkInterface.h"
+ 
+/** CellularInterface class
+ *
+ *  Common interface that is shared between ethernet hardware
+ */
+class CellularInterface : public NetworkInterface
+{
+public:
+    /** Start the interface
+     *
+     *  @param apn      Optional name of the network to connect to
+     *  @param username Optional username for your APN
+     *  @param password Optional password for your APN 
+     *  @return         0 on success, negative error code on failure
+     */
+    virtual int connect(const char *apn = 0, const char *username = 0, const char *password = 0) = 0;
+ 
+    /** Stop the interface
+     *
+     *  @return         0 on success, negative error code on failure
+     */
+    virtual int disconnect() = 0;
+};
+ 
+#endif

EthernetInterface.h

@@ -1,4 +1,4 @@
-/* Socket
+/* EthernetInterface
  * Copyright (c) 2015 ARM Limited
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
@@ -20,18 +20,21 @@
 #include "NetworkInterface.h"
 
 /** EthernetInterface class
- *  Common interface that is shared between ethernet hardware
+ *
+ *  Common interface that is shared between ethernet hardware.
  */
 class EthernetInterface : public NetworkInterface
 {
 public:
     /** Start the interface
-     *  @return     0 on success, negative on failure
+     *
+     *  @return     0 on success, negative error code on failure
      */
     virtual int connect() = 0;
 
     /** Stop the interface
-     *  @return     0 on success, negative on failure
+     *
+     *  @return     0 on success, negative error code on failure
      */
     virtual int disconnect() = 0;
 };

MeshInterface.h

@@ -1,4 +1,4 @@
-/* Socket
+/* MeshInterface
  * Copyright (c) 2015 ARM Limited
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
@@ -20,17 +20,20 @@
 #include "NetworkInterface.h"
 
 /** MeshInterface class
- *  Common interface that is shared between ethernet hardware
+ *
+ *  Common interface that is shared between mesh hardware
  */
 class MeshInterface : public NetworkInterface
 {
 public:
     /** Start the interface
+     *
      *  @return     0 on success, negative on failure
      */
     virtual int connect() = 0;
 
     /** Stop the interface
+     *
      *  @return     0 on success, negative on failure
      */
     virtual int disconnect() = 0;

NetworkInterface.h

@@ -46,7 +46,7 @@ enum nsapi_error_t {
  *  The socket protocol specifies a particular protocol to
  *  be used with a newly created socket. 
  *
- *  @enum protocol_t
+ *  @enum nsapi_protocol_t
  */
 enum nsapi_protocol_t {
    NSAPI_TCP, /*!< Socket is of TCP type */
@@ -74,26 +74,29 @@ class NetworkInterface
 public:
     virtual ~NetworkInterface() {};
 
-    /** Get the internally stored IP address
+    /** Get the local IP address
      *
-     *  @return         IP address of the interface or null if not yet connected
+     *  @return         Null-terminated representation of the local IP address
+     *                  or null if not yet connected
      */
     virtual const char *get_ip_address() = 0;
 
-    /** Get the internally stored MAC address
+    /** Get the local MAC address
      *
-     *  @return         MAC address of the interface
+     *  @return         Null-terminated representation of the local MAC address
      */
     virtual const char *get_mac_address() = 0;
 
-    /** Translates a host name to an IP address
+    /** Translates a hostname to an IP address
      *
-     *  The host name may be either a domain name or an IP address.
-     *  If no stack-specific DNS resolution is provided, the host name
+     *  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.
+     *  
+     *  If no stack-specific DNS resolution is provided, the hostname
      *  will be resolve using a UDP socket on the stack. 
      *
      *  @param address  Destination for the host SocketAddress
-     *  @param host     Host name to lookup
+     *  @param host     Hostname to resolve
      *  @return         0 on success, negative error code on failure
      */
     virtual int gethostbyname(SocketAddress *address, const char *host);

SocketAddress.h

@@ -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 @@ enum nsapi_version_t {
 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;
 

TCPServer.h

@@ -1,4 +1,4 @@
-/* Socket
+/* TCPServer
  * Copyright (c) 2015 ARM Limited
  *
  * Licensed under the Apache License, Version 2.0 (the "License");

TCPSocket.h

@@ -1,4 +1,4 @@
-/* Socket
+/* TCPSocket
  * Copyright (c) 2015 ARM Limited
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
@@ -53,7 +53,7 @@ class TCPSocket : public Socket {
      *  Initiates a connection to a remote server specified by either
      *  a domain name or an IP address and a port.
      *
-     *  @param host     Host name of the remote host
+     *  @param host     Hostname of the remote host
      *  @param port     Port of the remote host
      *  @return         0 on success, negative error code on failure
      */

UDPSocket.h

@@ -1,4 +1,4 @@
-/* Socket
+/* UDPSocket
  * Copyright (c) 2015 ARM Limited
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
@@ -58,7 +58,7 @@ class UDPSocket : public Socket {
      *  non-blocking or times out, NSAPI_ERROR_WOULD_BLOCK is returned
      *  immediately.
      *
-     *  @param host     Host name of the remote host
+     *  @param host     Hostname of the remote host
      *  @param port     Port of the remote host
      *  @param data     Buffer of data to send to the host
      *  @param size     Size of the buffer in bytes

WiFiInterface.h

@@ -1,4 +1,4 @@
-/* Socket
+/* WiFiInterface
  * Copyright (c) 2015 ARM Limited
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
@@ -19,7 +19,12 @@
 
 #include "NetworkInterface.h"
 
-/** Enum for WiFi encryption types
+/** Enum of WiFi encryption types
+ *
+ *  The security type specifies a particular security to use when
+ *  connected to a WiFi network
+ *
+ *  @enum nsapi_protocol_t
  */
 enum nsapi_security_t {
     NSAPI_SECURITY_NONE = 0,   /*!< open access point */
@@ -29,21 +34,27 @@ enum nsapi_security_t {
 };
 
 /** WiFiInterface class
+ *
  *  Common interface that is shared between WiFi devices
  */
 class WiFiInterface : public NetworkInterface
 {
 public:
     /** Start the interface
+     *
+     *  Attempts to connect to a WiFi network. If passphrase is invalid,
+     *  NSAPI_ERROR_AUTH_ERROR is returned.
+     *
      *  @param ssid      Name of the network to connect to
      *  @param pass      Security passphrase to connect to the network
      *  @param security  Type of encryption for connection
-     *  @return          0 on success, negative on failure
+     *  @return          0 on success, negative error code on failure
      */
     virtual int connect(const char *ssid, const char *pass, nsapi_security_t security = NSAPI_SECURITY_NONE) = 0;
 
     /** Stop the interface
-     *  @return          0 on success, negative on failure
+     *
+     *  @return          0 on success, negative error code on failure
      */
     virtual int disconnect() = 0;
 };