From 30a3ec8e0d491485fb5b74225b9eb7e8773642f7 Mon Sep 17 00:00:00 2001
From: Ari Parkkila <ari.parkkila@arm.com>
Date: Mon, 12 Feb 2018 13:39:17 +0200
Subject: [PATCH] Updated cellular doxygen

---
 .../easy_cellular/CellularConnectionUtil.cpp  | 11 ----
 .../easy_cellular/CellularConnectionUtil.h    | 64 ++++++++++++++++---
 .../easy_cellular/EasyCellularConnection.cpp  |  5 +-
 .../easy_cellular/EasyCellularConnection.h    | 10 +--
 4 files changed, 63 insertions(+), 27 deletions(-)

diff --git a/features/cellular/easy_cellular/CellularConnectionUtil.cpp b/features/cellular/easy_cellular/CellularConnectionUtil.cpp
index d65b556179..2700cbbddb 100644
--- a/features/cellular/easy_cellular/CellularConnectionUtil.cpp
+++ b/features/cellular/easy_cellular/CellularConnectionUtil.cpp
@@ -477,17 +477,6 @@ nsapi_error_t CellularConnectionUtil::start_dispatch()
     return NSAPI_ERROR_OK;
 }
 
-nsapi_error_t CellularConnectionUtil::disconnect()
-{
-    log_info("CellularConnectionUtil::disconnect");
-    nsapi_error_t err = NSAPI_ERROR_OK;
-    if (_network) {
-        err = _network->disconnect();
-    }
-
-    return err;
-}
-
 void CellularConnectionUtil::stop()
 {
     log_info("CellularConnectionUtil::stop");
diff --git a/features/cellular/easy_cellular/CellularConnectionUtil.h b/features/cellular/easy_cellular/CellularConnectionUtil.h
index f36dedba30..66398f32b9 100644
--- a/features/cellular/easy_cellular/CellularConnectionUtil.h
+++ b/features/cellular/easy_cellular/CellularConnectionUtil.h
@@ -33,9 +33,19 @@
 
 const int PIN_SIZE = 8;
 
+/** CellularConnectionUtil class
+ *
+ *  Utility class for cellular connection
+ */
 class CellularConnectionUtil
 {
 public:
+    CellularConnectionUtil();
+    virtual ~CellularConnectionUtil();
+
+public:
+    /** Cellular connection states
+     */
     enum CellularState {
         STATE_POWER_ON = 0,
         STATE_DEVICE_READY = 1,
@@ -50,24 +60,58 @@ public:
     };
 
 public:
-    CellularConnectionUtil();
-    virtual ~CellularConnectionUtil();
-    void set_serial(UARTSerial *serial);
-    void set_callback(mbed::Callback<bool(int, int)> status_callback);
-    EventQueue* get_queue();
-    nsapi_error_t start_dispatch();
+    /** Initialize cellular device
+     *  @remark Must be called before any other methods
+     *  @return see nsapi_error_t, 0 on success
+     */
     nsapi_error_t init();
 
+    /** Set serial connection for cellular device
+     *  @param serial UART driver
+     */
+    void set_serial(UARTSerial *serial);
 
-    nsapi_error_t disconnect();
+    /** Set callback for state update
+     *  @param status_callback function to call on state changes
+     */
+    void set_callback(mbed::Callback<bool(int, int)> status_callback);
+    
+    /** Get event queue that can be chained to main event queue (or use start_dispatch)
+     *  @return event queue
+     */
+    EventQueue* get_queue();
+
+    /** Start event queue dispatching
+     *  @return see nsapi_error_t, 0 on success
+     */
+    nsapi_error_t start_dispatch();
+
+    /** Stop event queue dispatching and close cellular interfaces
+     */
     void stop();
+    
+    /** Get cellular network interface
+     *  @return network interface, NULL on failure
+     */
     CellularNetwork* get_network();
+
+    /** Get cellular device interface
+     *  @return device interface, NULL on failure
+     */
     CellularDevice* get_device();
+
+    /** Change cellular connection to the target state
+     *  @param state to continue
+     *  @return see nsapi_error_t, 0 on success
+     */
     nsapi_error_t continue_to_state(CellularState state);
 
-    void set_sim_pin(const char * sim_pin);
+    /** Set cellular device SIM PIN code
+     *  @param sim_pin PIN code
+     */
+    void set_sim_pin(const char *sim_pin);
 
-protected:
+private:
     bool open_power(FileHandle *fh);
     bool open_sim();
     bool open_network();
@@ -76,7 +120,7 @@ protected:
     bool get_attach_network(CellularNetwork::AttachStatus &status);
     bool set_attach_network();
 
-protected:
+private:
     friend class EasyCellularConnection;
     NetworkStack *get_stack();
 
diff --git a/features/cellular/easy_cellular/EasyCellularConnection.cpp b/features/cellular/easy_cellular/EasyCellularConnection.cpp
index 669437b916..85b157960c 100644
--- a/features/cellular/easy_cellular/EasyCellularConnection.cpp
+++ b/features/cellular/easy_cellular/EasyCellularConnection.cpp
@@ -116,7 +116,10 @@ nsapi_error_t EasyCellularConnection::connect()
 nsapi_error_t EasyCellularConnection::disconnect()
 {
     _is_connected = false;
-    return cellularConnection.disconnect();
+    if (!cellularConnection.get_network()) {
+        return NSAPI_ERROR_NO_CONNECTION;
+    }
+    return cellularConnection.get_network()->disconnect();
 }
 
 bool EasyCellularConnection::is_connected()
diff --git a/features/cellular/easy_cellular/EasyCellularConnection.h b/features/cellular/easy_cellular/EasyCellularConnection.h
index 705d371861..ec98b87e86 100644
--- a/features/cellular/easy_cellular/EasyCellularConnection.h
+++ b/features/cellular/easy_cellular/EasyCellularConnection.h
@@ -19,9 +19,9 @@
 #include "netsocket/CellularBase.h"
 #include "CellularConnectionUtil.h"
 
-/** ExampleCellularBase class
+/** EasyCellularConnection class
  *
- *  A simplified example about how to use cellular
+ *  Simplified adapter for cellular connection
  */
 class EasyCellularConnection: public CellularBase {
 
@@ -30,9 +30,9 @@ public:
     virtual ~EasyCellularConnection();
 
 public:
-
-    /**
-     * MUST CALL, create power and start dispatcher
+    /** Create cellular power and start dispatcher
+     *  @remark Must be called before any other methods
+     *  @return see nsapi_error_t, 0 on success
      */
     nsapi_error_t init();