Merge pull request #9655 from mirelachirica/nonip_doxygen_updates

Cellular: Non-IP doxygen updates

Author: Cruz Monrreal

features/cellular/framework/API/CellularContext.h

@@ -21,6 +21,11 @@
 #include "CellularDevice.h"
 #include "ControlPlane_netif.h"
 
+/** @file CellularContext.h
+ * @brief Cellular PDP context class
+ *
+ */
+
 namespace mbed {
 
 typedef enum pdp_type {

features/cellular/framework/API/CellularDevice.h

@@ -24,6 +24,10 @@
 #include "ATHandler.h"
 #include "UARTSerial.h"
 
+/** @file CellularDevice.h
+ * @brief Class CellularDevice
+ *
+ */
 namespace mbed {
 
 class CellularSMS;
@@ -168,7 +172,7 @@ class CellularDevice {
      *  @param fh       file handle used in communication to modem. This can be, for example, UART handle. If null, then the default
      *                  file handle is used.
      *  @param apn      access point to use with context, can be null.
-     *  @param cp_req       flag indicating if EPS control plane optimisation is required
+     *  @param cp_req       flag indicating if EPS control plane optimization is required
      *  @param nonip_req    flag indicating if this context is required to be Non-IP
      *
      *  @return         new instance of class CellularContext or NULL in case of failure
@@ -184,7 +188,7 @@ class CellularDevice {
      *  @param apn          access point to use with context, can be null.
      *  @param dcd_pin      Pin used to set data carrier detect on/off for the given UART
      *  @param active_high  a boolean set to true if DCD polarity is active low
-     *  @param cp_req       Flag indicating if EPS control plane optimisation is required
+     *  @param cp_req       Flag indicating if EPS control plane optimization is required
      *  @param nonip_req    Flag indicating if this context is required to be Non-IP
      *
      *  @return         new instance of class CellularContext or NULL in case of failure

features/cellular/framework/API/CellularNetwork.h

@@ -260,7 +260,7 @@ class CellularNetwork {
      *  @param supported_opt Supported CIoT EPS optimizations
      *                       (the HW support can be checked with get_ciot_ue_optimization_config).
      *  @param preferred_opt Preferred CIoT EPS optimizations.
-     *  @param network_support_cb This callback will be called when CIoT network optimisation support is known
+     *  @param network_support_cb This callback will be called when CIoT network optimization support is known
      *  @return              NSAPI_ERROR_OK on success
      *                       NSAPI_ERROR_DEVICE_ERROR on failure
      */

features/cellular/framework/AT/AT_CellularContext.cpp

@@ -460,7 +460,7 @@ nsapi_error_t AT_CellularContext::do_activate_context()
     }
 
     // In IP case but also when Non-IP is requested and
-    // control plane optimisation is not established -> activate ip context
+    // control plane optimization is not established -> activate ip context
     _nonip_req = false;
     return activate_ip_context();
 }

features/cellular/framework/AT/AT_CellularContext.h

@@ -135,7 +135,7 @@ class AT_CellularContext : public CellularContext, public AT_CellularBase {
     // flag indicating if Non-IP context was requested to be setup
     bool _nonip_req;
 
-    // tells if CCIOTOPTI received green from network for CP optimisation use
+    // tells if CCIOTOPTI received green from network for CP optimization use
     bool _cp_in_use;
 };
 

features/cellular/framework/AT/AT_CellularDevice.h

@@ -99,9 +99,11 @@ class AT_CellularDevice : public CellularDevice {
 
     /** Creates new instance of AT_CellularContext or if overridden, modem specific implementation.
      *
-     *  @param at       ATHandler reference for communication with the modem.
-     *  @param apn      access point to use with context
-     *  @return         new instance of class AT_CellularContext
+     *  @param at           ATHandler reference for communication with the modem.
+     *  @param apn          access point to use with context
+     *  @param cp_req       flag indicating if control plane EPS optimization needs to be setup
+     *  @param nonip_req    flag indicating if PDP context needs to be Non-IP
+     *  @return             new instance of class AT_CellularContext
      *
      */
     virtual AT_CellularContext *create_context_impl(ATHandler &at, const char *apn, bool cp_req = false, bool nonip_req = false);

features/cellular/framework/AT/AT_ControlPlane_netif.h

@@ -12,10 +12,18 @@ class AT_ControlPlane_netif: public ControlPlane_netif, public AT_CellularBase {
 protected:
 
 // ControlPlane_netif
-    // +CSODCP: 3GPP 27007 10.1.43
+
+    /* Sends data using +CSODCP specified in
+     *  3GPP 27007 10.1.43: Sending of originating data via the control plane
+     */
     virtual nsapi_size_or_error_t send(const void *cpdata, nsapi_size_t cpdata_length);
-    // +CRTDCP: 3GPP 27007 10.1.44
+
+
+    /* Receives data using +CRTDCP specified in
+     *  3GPP 27007 10.1.44: Reporting of terminating data via the control plane
+     */
     virtual nsapi_size_or_error_t recv(void *cpdata, nsapi_size_t cpdata_length);
+
     virtual void data_received();
     virtual void attach(void (*callback)(void *), void *data);
 
@@ -27,6 +35,7 @@ class AT_ControlPlane_netif: public ControlPlane_netif, public AT_CellularBase {
     void *_data;
     char _recv_buffer[MAX_CP_DATA_RECV_LEN];
     size_t _recv_len;
+    // Called on receiving URC: +CRTDCP
     void urc_cp_recv();
 };
 

features/cellular/mbed_lib.json

@@ -18,7 +18,7 @@
             "value": null
         },
         "control-plane-opt": {
-            "help": "Enables control plane CIoT EPS optimisation",
+            "help": "Enables control plane CIoT EPS optimization",
             "value": false
         }
     }

features/netsocket/cellular/CellularNonIPSocket.h

@@ -1,7 +1,4 @@
-
-/** \addtogroup netsocket */
-/** @{*/
-/* Socket
+/* CellularNonIPSocket
  * Copyright (c) 2015 ARM Limited
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
@@ -30,7 +27,13 @@
 
 namespace mbed {
 
-//Socket implementation for non ip datagrams over cellular control plane
+/** \addtogroup netsocket */
+/** @{*/
+
+/** Socket implementation for cellular Non-IP data delivery(NIDD).
+ *  Relies on Control Plane CIoT EPS optimization feature,
+ *  implemented in ControlPlane_netif class.
+ */
 class CellularNonIPSocket : public Socket {
 public:
     /** Destroy the socket.
@@ -101,25 +104,33 @@ class CellularNonIPSocket : public Socket {
      */
     virtual void set_blocking(bool blocking);
 
-    /** @copydoc Socket::set_blocking
+    /** @copydoc Socket::set_timeout
      */
     virtual void set_timeout(int timeout);
 
     /** @copydoc Socket::sigio
      */
     virtual void sigio(mbed::Callback<void()> func);
 
-    // NOT SUPPORTED
+    /// NOT APPLICABLE
     virtual nsapi_error_t connect(const SocketAddress &address);
+    /// NOT APPLICABLE
     virtual Socket *accept(nsapi_error_t *error = NULL);
+    /// NOT APPLICABLE
     virtual nsapi_error_t listen(int backlog = 1);
+    /// NOT APPLICABLE
     virtual nsapi_error_t setsockopt(int level, int optname, const void *optval, unsigned optlen);
+    /// NOT APPLICABLE
     virtual nsapi_error_t getsockopt(int level, int optname, void *optval, unsigned *optlen);
+    /// NOT APPLICABLE
     virtual nsapi_error_t getpeername(SocketAddress *address);
+    /// NOT APPLICABLE
     virtual nsapi_size_or_error_t sendto(const SocketAddress &address,
                                          const void *data, nsapi_size_t size);
+    /// NOT APPLICABLE
     virtual nsapi_size_or_error_t recvfrom(SocketAddress *address,
                                            void *data, nsapi_size_t size);
+    /// NOT APPLICABLE
     virtual nsapi_error_t bind(const SocketAddress &address);
 
 protected:
@@ -143,8 +154,7 @@ class CellularNonIPSocket : public Socket {
     bool _opened;
 };
 
+/** @}*/
 } // namespace mbed
 
 #endif // CELLULARNONIPSOCKET_H
-
-/** @}*/

features/netsocket/cellular/ControlPlane_netif.h

@@ -19,12 +19,26 @@
 
 #include "nsapi_types.h"
 
+/** @file ControlPlane_netif.h
+ * @brief Implements support for data transfer using Control Plane CIoT EPS optimization.
+ *
+ */
+
 namespace mbed {
 
 /* Length of the buffer storing data received over control plane */
 #define MAX_CP_DATA_RECV_LEN 2048
 
 // TODO: need to make this l3ip compatible
+
+/**
+ * @addtogroup cellular
+ * @{
+ */
+
+/** Implements support for data transfer using
+ *  Control Plane CIoT EPS optimization specified in 3GPP 23.401(4.10), 3GPP 23.682(4.5.14).
+ */
 class ControlPlane_netif {
 public:
     ControlPlane_netif() {}
@@ -58,8 +72,6 @@ class ControlPlane_netif {
     *  is received from network. It will invoke the callback set
     *  by the above attach.
     *
-    *  @param buffer     Buffer containing received data
-    *  @param size       Size of data in bytes
     */
     virtual void data_received() = 0;
 
@@ -78,5 +90,9 @@ class ControlPlane_netif {
     virtual void attach(void (*callback)(void *), void *data) = 0;
 };
 
+/**
+ * @}
+ */
+
 } // mbed namespace
 #endif