Revisited documentation for Socket API

Author: geky

NetworkInterface.h

@@ -1,4 +1,4 @@
-/* Socket
+/* NetworkInterface
  * Copyright (c) 2015 ARM Limited
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
@@ -134,8 +134,8 @@ class NetworkInterface
 
     /** Opens a socket
      *
-     *  Creates a socket for communication and stores it in the specified
-     *  handle. The handle must be passed to following calls on the socket.
+     *  Creates a network socket and stores it in the specified handle.
+     *  The handle must be passed to following calls on the socket.
      *
      *  A stack may have a finite number of sockets, in this case
      *  NSAPI_ERROR_NO_SOCKET is returned if no socket is available.
@@ -148,8 +148,8 @@ class NetworkInterface
 
     /** Close the socket
      *
-     *  Closes any open connection and deallocates any memory associated with
-     *  the socket.
+     *  Closes any open connection and deallocates any memory associated
+     *  with the socket.
      *
      *  @param handle   Socket handle
      *  @return         0 on success, negative error code on failure
@@ -174,7 +174,7 @@ class NetworkInterface
      *
      *  @param handle   Socket handle
      *  @param backlog  Number of pending connections that can be queued
-     *                  simultaneously, defaults to 1
+     *                  simultaneously
      *  @return         0 on success, negative error code on failure
      */
     virtual int socket_listen(void *handle, int backlog) = 0;
@@ -193,8 +193,9 @@ class NetworkInterface
     /** Accepts a connection on a TCP socket
      *
      *  The server socket must be bound and set to listen for connections.
-     *  On a new connection, creates a socket stores it in the specified
-     *  handle. The handle must be passed to following calls on the socket.
+     *  On a new connection, creates a network socket and stores it in the
+     *  specified handle. The handle must be passed to following calls on
+     *  the socket.
      *
      *  A stack may have a finite number of sockets, in this case
      *  NSAPI_ERROR_NO_SOCKET is returned if no socket is available.
@@ -289,7 +290,7 @@ class NetworkInterface
      */
     virtual void socket_attach(void *handle, void (*callback)(void *), void *data) = 0;
 
-    /*  Set stack-specific socked options
+    /*  Set stack-specific socket options
      *
      *  The setsockopt allow an application to pass stack-specific hints
      *  to the underlying stack. For unsupported options,

Socket.h

@@ -24,74 +24,135 @@
  */
 class Socket {
 public:
-    /** Socket lifetime
+    /** Destroy a socket
+     *
+     *  Closes socket if the socket is still open
      */
     virtual ~Socket();
 
-    /** Open the socket
-     *  @param iface    Interface to open socket on
+    /** Opens a socket
+     *
+     *  Creates a network socket on the specified network stack.
+     *  Not needed if stack is passed to the socket's constructor.
+     *
+     *  @param iface    Network stack as target for socket
+     *  @return         0 on success, negative error code on failure
      */
     virtual int open(NetworkInterface *iface) = 0;
 
     /** Close the socket
+     *
+     *  Closes any open connection and deallocates any memory associated
+     *  with the socket. Called from destructor if socket is not closed.
+     *
+     *  @return         0 on success, negative error code on failure
      */
     int close();
 
-    /** Bind a socket to a specific port
-     *  @param port     The port to listen for incoming connections on
-     *  @return         0 on success, negative on failure.
+    /** Bind a specific address to a socket
+     *
+     *  Binding a socket specifies the address and port on which to recieve
+     *  data.
+     *
+     *  @param port     Local port to bind
+     *  @return         0 on success, negative error code on failure.
      */
     int bind(uint16_t port);
 
-    /** Bind a socket to a specific port
-     *  @param address  The null-terminated address to listen for incoming connections on
-     *  @param port     The port to listen for incoming connections on
-     *  @return         0 on success, negative on failure.
+    /** Bind a specific address to a socket
+     *
+     *  Binding a socket specifies the address and port on which to recieve
+     *  data. If the IP address is zeroed, only the port is bound.
+     *
+     *  @param address  Null-terminated local address to bind
+     *  @param port     Local port to bind
+     *  @return         0 on success, negative error code on failure.
      */
     int bind(const char *address, uint16_t port);
 
-    /** Bind a socket to a specific port
-     *  @param address  The SocketAddress to listen for incoming connections on
-     *  @return         0 on success, negative on failure.
+    /** Bind a specific address to a socket
+     *
+     *  Binding a socket specifies the address and port on which to recieve
+     *  data. If the IP address is zeroed, only the port is bound.
+     *
+     *  @param address  Local address to bind
+     *  @return         0 on success, negative error code on failure.
      */
     int bind(const SocketAddress &address);
 
     /** Set blocking or non-blocking mode of the socket
-     *  @param blocking true for blocking mode, false for non-blocking mode.
+     *
+     *  Initially all sockets are in blocking mode. In non-blocking mode
+     *  blocking operations such as send/recv/accept return
+     *  NSAPI_ERROR_WOULD_BLOCK if they can not continue.
+     *
+     *  @param blocking True for blocking mode, false for non-blocking mode.
      */
     void set_blocking(bool blocking);
 
-    /** Set timeout on a socket operation if blocking behaviour is enabled
-     *  @param timeout  timeout in ms
+    /** Set timeout on blocking socket operations
+     *
+     *  Initially all sockets have unbounded timeouts. NSAPI_ERROR_WOULD_BLOCK
+     *  is returned if a blocking operation takes longer than the specified
+     *  timeout. A timeout of 0 removes a timeout from the socket.
+     *
+     *  @param timeout  Timeout in milliseconds
      */
     void set_timeout(unsigned int timeout);
 
-    /*  Set socket options
-     *  @param level    Option level
-     *  @param optname  Option identifier
+    /*  Set stack-specific socket options
+     *
+     *  The setsockopt allow an application to pass stack-specific hints
+     *  to the underlying stack. For unsupported options,
+     *  NSAPI_ERROR_UNSUPPORTED is returned and the socket is unmodified.
+     *
+     *  @param level    Stack-specific protocol level
+     *  @param optname  Stack-specific option identifier
      *  @param optval   Option value
      *  @param optlen   Length of the option value
-     *  @return         0 on success, negative on failure
+     *  @return         0 on success, negative error code on failure
      */    
     int setsockopt(int level, int optname, const void *optval, unsigned optlen);
 
-    /*  Get socket options
-     *  @param level    Option level
-     *  @param optname  Option identifier
-     *  @param optval   Buffer where to write option value
+    /*  Get stack-specific socket options
+     *
+     *  The getstackopt allow an application to retrieve stack-specific hints
+     *  from the underlying stack. For unsupported options,
+     *  NSAPI_ERROR_UNSUPPORTED is returned and optval is unmodified.
+     *
+     *  @param level    Stack-specific protocol level
+     *  @param optname  Stack-specific option identifier
+     *  @param optval   Destination for option value
      *  @param optlen   Length of the option value
-     *  @return         0 on success, negative on failure
+     *  @return         0 on success, negative error code on failure
      */    
     int getsockopt(int level, int optname, void *optval, unsigned *optlen);
 
     /** Register a callback on state change of the socket
+     *
+     *  The specified callback will be called on state changes such as when
+     *  the socket can recv/send/accept successfully and on when an error
+     *  occurs. The callback may also be called spuriously without reason.
+     *
+     *  The callback may be called in an interrupt context and should not
+     *  perform expensive operations such as recv/send calls.
+     *
      *  @param callback Function to call on state change
-     *  @note Callback may be called in an interrupt context.
-     *        The callback should not perform long operations 
-     *        such as recv or send calls.
      */
     void attach(FunctionPointer callback);
 
+    /** Register a callback on state change of the socket
+     *
+     *  The specified callback will be called on state changes such as when
+     *  the socket can recv/send/accept successfully and on when an error
+     *  occurs. The callback may also be called spuriously without reason.
+     *
+     *  The callback may be called in an interrupt context and should not
+     *  perform expensive operations such as recv/send calls.
+     *
+     *  @param tptr     Pointer to object to call method on
+     *  @param mptr     Method to call on state change
+     */
     template <typename T, typename M>
     void attach(T *tptr, M mptr) {
         attach(FunctionPointer(tptr, mptr));

TCPServer.h

@@ -21,31 +21,57 @@
 #include "TCPSocket.h"
 #include "NetworkInterface.h"
 
-/** TCP Server.
+/** TCP socket server
   */
 class TCPServer : public Socket {
 public:
-    /** TCP Server lifetime
+    /** Create an uninitialized socket
+     *
+     *  Must call open to initialize the socket on a network stack.
      */
     TCPServer();
+
+    /** Create a socket on a network stack
+     *
+     *  Creates and opens a socket on the specified network stack.
+     *
+     *  @param iface    Network stack as target for socket
+     */
     TCPServer(NetworkInterface *iface);
-    virtual ~TCPServer();
 
-    /** Open the socket
-     *  @param iface    Interface to open socket on
+    /** Opens a socket
+     *
+     *  Creates a network socket on the specified network stack.
+     *  Not needed if stack is passed to the socket's constructor.
+     *
+     *  @param iface    Network stack as target for socket
+     *  @return         0 on success, negative error code on failure
      */
     virtual int open(NetworkInterface *iface);
 
-    /** Start listening for incoming connections
-     * @param backlog   Number of pending connections that can be queued up at any
-     *                  one time [Default: 1]
-     * @return          0 on success, negative on failure
+    /** Listen for connections on a TCP socket
+     *
+     *  Marks the socket as a passive socket that can be used to accept
+     *  incoming connections.
+     *
+     *  @param backlog  Number of pending connections that can be queued
+     *                  simultaneously, defaults to 1
+     *  @return         0 on success, negative error code on failure
      */
-    int listen(int backlog=1);
+    int listen(int backlog = 1);
 
-    /** Accept a new connection.
-     * @param socket    A TCPSocket instance that will handle the incoming connection.
-     * @return          0 on success, negative on failure.
+    /** Accepts a connection on a TCP socket
+     *
+     *  The server socket must be bound and set to listen for connections.
+     *  On a new connection, creates a network socket using the specified
+     *  socket instance.
+     *
+     *  By default, accept blocks until data is sent. If socket is set to
+     *  non-blocking or times out, NSAPI_ERROR_WOULD_BLOCK is returned
+     *  immediately.
+     *
+     *  @param socket   TCPSocket instance that will handle the incoming connection.
+     *  @return         0 on success, negative error code on failure
      */
     int accept(TCPSocket *connection);
 };

TCPSocket.h

@@ -24,41 +24,80 @@
  */
 class TCPSocket : public Socket {
 public:
-    /** TCP socket lifetime
+    /** Create an uninitialized socket
+     *
+     *  Must call open to initialize the socket on a network stack.
      */
     TCPSocket();
+
+    /** Create a socket on a network stack
+     *
+     *  Creates and opens a socket on the specified network stack.
+     *
+     *  @param iface    Network stack as target for socket
+     */
     TCPSocket(NetworkInterface *iface);
 
-    /** Open the socket
-     *  @param iface    Interface to open socket on
+    /** Opens a socket
+     *
+     *  Creates a network socket on the specified network stack.
+     *  Not needed if stack is passed to the socket's constructor.
+     *
+     *  @param iface    Network stack as target for socket
+     *  @return         0 on success, negative error code on failure
      */
     virtual int open(NetworkInterface *iface);
-    
-    /** Connects this TCP socket to the server
-     *  @param host     The host to connect to. It can either be an IP Address
-     *                  or a hostname that will be resolved with DNS
-     *  @param port     The host's port to connect to
-     *  @return         0 on success, negative on failure
+
+    /** Connects TCP socket to a remote host
+     *
+     *  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 port     Port of the remote host
+     *  @return         0 on success, negative error code on failure
      */
     int connect(const char *host, uint16_t port);
 
-    /** Connects this TCP socket to the server
-     *  @param address  SocketAddress to connect to
-     *  @return         0 on success, negative on failure
+    /** Connects TCP socket to a remote host
+     *
+     *  Initiates a connection to a remote server specified by the
+     *  indicated address.
+     *
+     *  @param address  The SocketAddress of the remote host
+     *  @return         0 on success, negative error code on failure
      */
     int connect(const SocketAddress &address);
 
-    /** Send data to the remote host
-     *  @param data     The buffer to send to the host
-     *  @param size     The length of the buffer to send
-     *  @return         Number of written bytes on success, negative on failure
+    /** Send data over a TCP socket
+     *
+     *  The socket must be connected to a remote host. Returns the number of
+     *  bytes sent from the buffer.
+     *
+     *  By default, send blocks until data is sent. If socket is set to
+     *  non-blocking or times out, NSAPI_ERROR_WOULD_BLOCK is returned
+     *  immediately.
+     *
+     *  @param data     Buffer of data to send to the host
+     *  @param size     Size of the buffer in bytes
+     *  @return         Number of sent bytes on success, negative error
+     *                  code on failure
      */
     int send(const void *data, unsigned size);
 
-    /** Receive data from the remote host
-     *  @param data     The buffer in which to store the data received from the host
-     *  @param size     The maximum length of the buffer
-     *  @return         Number of received bytes on success, negative on failure
+    /** Receive data over a TCP socket
+     *
+     *  The socket must be connected to a remote host. Returns the number of
+     *  bytes received into the buffer.
+     *
+     *  By default, recv blocks until data is sent. If socket is set to
+     *  non-blocking or times out, NSAPI_ERROR_WOULD_BLOCK is returned
+     *  immediately.
+     *
+     *  @param data     Destination buffer for data received from the host
+     *  @param size     Size of the buffer in bytes
+     *  @return         Number of received bytes on success, negative error
+     *                  code on failure
      */
     int recv(void *data, unsigned size);