Merge pull request #9328 from SeppoTakalo/ip-core-doxygen

Doxygen fixes for IP networking area

Author: 0xc0170

doxyfile_options

@@ -859,7 +859,10 @@ EXCLUDE_PATTERNS       = */tools/* \
                          */ble/pal/* \
                          */components/802.15.4_RF/* \
                          */components/wifi/* \
-                         */UNITTESTS/*
+                         */UNITTESTS/* \
+                         */features/cellular/framework/AT/* \
+                         */features/cellular/framework/device/* \
+                         */features/cellular/framework/common/*
 
 # The EXCLUDE_SYMBOLS tag can be used to specify one or more symbol names
 # (namespaces, classes, functions, etc.) that should be excluded from the

features/cellular/README.md

@@ -2,26 +2,21 @@
 
 This is the Github repo for Mbed cellular connectivity:
 
-    easy_cellular/
-        EasyCellularConnection  Simplified cellular usage based on `CellularBase.h`
-        CellularConnectionUtil  A utility class for cellular connection
-
     framework/
         API         Application Programming Interface for cellular connectivity
         AT          AT implementation based on 3GPP TS 27.007 specification
         common      Common and utility sources
+        device      Implementation of cellular device and state machine
         targets     Vendor specific cellular module adaptations
 
     TESTS           Cellular Greentea test
 
-    UNITTESTS       Cellular unit test
+**Note:** Application developers should use only the `API` folder.
 
 ## Known limitations
 
 **Please note that this is a first release of Cellular framework and is subject to further development in future.**
 
-Only UDP is supported when using AT commands to control sockets in an IP stack built into the cellular modem. If TCP is required, use the PPP/LWIP stack.
-
 ## Supported modules
 
 You can find currently supported cellular modules in the `framework/targets/` folder, where we also add support for new cellular modules.
@@ -30,57 +25,41 @@ You can find currently supported cellular modules in the `framework/targets/` fo
 
 You can change cellular defaults in the `mbed_lib.json` configuration file.
 
-You can also override cellular defaults in the `mbed_app.json` configuration file:
-
-    "config": {
-        "cellular_plmn": {
-            "help": "PLMN selection, 0=auto",
-            "value": 0
-        },
-        "apn": {
-            "help": "Access point name, e.g. internet",
-            "value": "\"internet\""
-        },
-        "cellular_sim_pin": {
-            "help": "PIN code",
-            "value": "\"1234\""
-        }
-    }
-
 ## Debug traces
 
 You can define the debug tracing level in the `mbed_app.json` configuration file:
-
-    "target_overrides": {
-        "*": {
-            "mbed-trace.enable": true,
-            "platform.stdio-convert-newlines": true,
-            "platform.stdio-baud-rate": 115200,
-            "platform.default-serial-baud-rate": 115200
-        }
-    },
-    "config": {
-        "trace-level": {
-            "help": "Options are TRACE_LEVEL_ERROR,TRACE_LEVEL_WARN,TRACE_LEVEL_INFO,TRACE_LEVEL_DEBUG",
-            "macro_name": "MBED_TRACE_MAX_LEVEL",
-            "value": "TRACE_LEVEL_INFO"
-        }
+```
+"target_overrides": {
+    "*": {
+        "mbed-trace.enable": true,
+        "platform.stdio-convert-newlines": true,
+        "platform.stdio-baud-rate": 115200,
+        "platform.default-serial-baud-rate": 115200
+    }
+},
+"config": {
+    "trace-level": {
+        "help": "Options are TRACE_LEVEL_ERROR,TRACE_LEVEL_WARN,TRACE_LEVEL_INFO,TRACE_LEVEL_DEBUG",
+        "macro_name": "MBED_TRACE_MAX_LEVEL",
+        "value": "TRACE_LEVEL_INFO"
     }
+}
+```
 
 ## Greentea tests
 
-The `TESTS` folder contains Greentea tests for cellular specific classes. You need to give relevant configuration file with `--app-config` parameter, e.g.:
+The `TESTS` folder contains Greentea tests for cellular specific classes. You need to give relevant configuration file with `--app-config` parameter, such as:
 
-    mbed test -n features-cellular-tests-* --app-config features\cellular\TESTS\socket\udp\template_mbed_app.json.txt -v
+```
+mbed test -n features-cellular-tests-* --app-config features\cellular\TESTS\socket\udp\template_mbed_app.json.txt -v
+```
 
-    Note that Greentea tests use SIM PIN so you need to change that or your SIM card may get locked.
+**Note:** Greentea tests use SIM PIN, so you need to change that or your SIM card may get locked.
 
 ## Unit tests
 
-The `UNITTESTS` folder contains unit tests for cellular specific classes. Unit tests are based on the stubbing method.
-
-You can run those tests locally by running `./run_tests` script under the `UNITTESTS/` folder.
+Cellular unit tests are in Mbed OS root `UNITTESTS`. Unit tests are based on the stubbing method.
 
 You need the following applications: `cpputest`, `gcov` and `lcov` (genhtml) for running the tests.
 
-After you have run the `run_tests` script, you can find test results under `UNITTESTS/results` folder and line and function coverages under the `UNITTESTS/coverages` folder.
+After you run the `run_tests` script, you can find test results in `UNITTESTS/results`, and line and function coverages in `UNITTESTS/coverages`.

features/cellular/framework/API/CellularContext.h

@@ -22,6 +22,12 @@
 
 namespace mbed {
 
+/**
+ * @addtogroup cellular
+ * @{
+ */
+
+/// CellularContext is CellularBase/NetworkInterface with extensions for cellular connectivity
 class CellularContext : public CellularBase {
 
 public:
@@ -50,7 +56,7 @@ class CellularContext : public CellularBase {
         Week
     };
 
-    /* PDP Context information */
+    /// PDP Context information
     struct pdpcontext_params_t {
         char apn[MAX_ACCESSPOINT_NAME_LENGTH + 1];
         char local_addr[MAX_IPV6_ADDR_IN_IPV4LIKE_DOTTED_FORMAT + 1];
@@ -255,6 +261,10 @@ class CellularContext : public CellularBase {
     const char *_pwd;
 };
 
+/**
+ * @}
+ */
+
 } // namespace mbed
 
 

features/cellular/framework/API/CellularDevice.h

@@ -36,6 +36,11 @@ class FileHandle;
 const int MAX_PIN_SIZE = 8;
 const int MAX_PLMN_SIZE = 16;
 
+/**
+ * @addtogroup cellular
+ * @{
+ */
+
 /**
  *  Class CellularDevice
  *
@@ -294,6 +299,10 @@ class CellularDevice {
     Callback<void(nsapi_event_t, intptr_t)> _status_cb;
 };
 
+/**
+ * @}
+ */
+
 } // namespace mbed
 
 #endif // CELLULAR_DEVICE_H_

features/cellular/framework/API/CellularInformation.h

@@ -23,6 +23,11 @@
 
 namespace mbed {
 
+/**
+ * @addtogroup cellular
+ * @{
+ */
+
 /**
  *  Class CellularInformation
  *
@@ -83,6 +88,10 @@ class CellularInformation {
     virtual nsapi_error_t get_serial_number(char *buf, size_t buf_size, SerialNumberType type = SN) = 0;
 };
 
+/**
+ * @}
+ */
+
 } // namespace mbed
 
 #endif // CELLULAR_INFORMATION_H_

features/cellular/framework/API/CellularNetwork.h

@@ -1,5 +1,4 @@
-/*
- * Copyright (c) 2017, Arm Limited and affiliates.
+/* Copyright (c) 2017,2018 Arm Limited and affiliates.
  * SPDX-License-Identifier: Apache-2.0
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
@@ -32,18 +31,16 @@ const int MAX_OPERATOR_NAME_LONG = 16;
 const int MAX_OPERATOR_NAME_SHORT = 8;
 
 /**
- *  Class CellularNetwork
- *
- *  An abstract interface for connecting to a network and getting information from it.
+ * @addtogroup cellular
+ * @{
  */
+
+/// An abstract interface for connecting to a network and getting information from it.
 class CellularNetwork {
 protected:
     // friend of CellularDevice so that it's the only way to close/delete this class.
     friend class CellularDevice;
 
-    /**
-     * virtual Destructor
-     */
     virtual ~CellularNetwork() {}
 
 public:
@@ -112,7 +109,7 @@ class CellularNetwork {
         RAT_MAX = 11 // to reserve string array
     };
 
-    // 3GPP TS 27.007 - 7.3 PLMN selection +COPS
+    /// 3GPP TS 27.007 - 7.3 PLMN selection +COPS
     struct operator_t {
         enum Status {
             Unknown,
@@ -141,6 +138,7 @@ class CellularNetwork {
 
     typedef CellularList<operator_t> operList_t;
 
+    /// Cellular operator names in numeric and alpha format
     struct operator_names_t {
         char numeric[MAX_OPERATOR_NAME_SHORT + 1];
         char alpha[MAX_OPERATOR_NAME_LONG + 1];
@@ -154,7 +152,7 @@ class CellularNetwork {
     };
     typedef CellularList<operator_names_t> operator_names_list;
 
-    /* Network registering mode */
+    /// Network registering mode
     enum NWRegisteringMode {
         NWModeAutomatic = 0,    // automatic registering
         NWModeManual,           // manual registering with plmn
@@ -163,7 +161,7 @@ class CellularNetwork {
         NWModeManualAutomatic   // if manual fails, fallback to automatic
     };
 
-    /* Network registration information */
+    /// Network registration information
     struct registration_params_t {
         RegistrationType _type;
         RegistrationStatus _status;
@@ -365,6 +363,10 @@ class CellularNetwork {
     virtual nsapi_error_t get_registration_params(RegistrationType type, registration_params_t &reg_params) = 0;
 };
 
+/**
+ * @}
+ */
+
 } // namespace mbed
 
 #endif // CELLULAR_NETWORK_H_

features/cellular/framework/API/CellularSMS.h

@@ -35,6 +35,11 @@ const uint16_t SMS_SIM_WAIT_TIME_MILLISECONDS = 200;
 
 const int SMS_ERROR_MULTIPART_ALL_PARTS_NOT_READ = -5001;
 
+/**
+ * @addtogroup cellular
+ * @{
+ */
+
 /**
  *  Class CellularSMS
  *
@@ -162,6 +167,10 @@ class CellularSMS {
     virtual void set_extra_sim_wait_time(int sim_wait_time) = 0;
 };
 
+/**
+ * @}
+ */
+
 } // namespace mbed
 
 #endif // CELLULAR_SMS_H_

features/cellular/framework/AT/ATHandler.h

@@ -53,16 +53,13 @@ enum DeviceErrorType {
     DeviceErrorTypeErrorCME     // AT ERROR CME
 };
 
-/* struct used when getting at response error. Defines error code and type */
+/** AT response error with error code and type */
 struct device_err_t {
     DeviceErrorType errType;
     int errCode;
 };
 
-/** Class ATHandler
- *
- *  Class for sending AT commands and parsing AT responses.
- */
+/// Class for sending AT commands and parsing AT responses.
 class ATHandler {
 
 public:

features/netsocket/CellularBase.h

@@ -13,13 +13,18 @@
  * limitations under the License.
  */
 
+/* @file CellularBase.h CellularBase */
+
+/** @addtogroup netinterface
+ * @{
+ */
+
 #ifndef CELLULAR_BASE_H
 #define CELLULAR_BASE_H
 
 #include "netsocket/NetworkInterface.h"
 
 /** Common interface that is shared between cellular interfaces.
- *  @addtogroup netsocket
  */
 class CellularBase: public NetworkInterface {
 

features/netsocket/DNS.h

@@ -14,9 +14,14 @@
  * limitations under the License.
  */
 
+/** @file DNS.h Domain Name Service */
+/** @addtogroup netsocket
+ * @{ */
+
 #ifndef DNS_H
 #define DNS_H
 
+/** Base class for DNS provider */
 class DNS {
 public:
 
@@ -95,3 +100,5 @@ class DNS {
 };
 
 #endif
+
+/** @} */