Merge pull request #8552 from cmonr/rollup

Rollup PR: UK Docathon pt2

Author: Cruz Monrreal

.github/issue_template.md

@@ -1,3 +1,19 @@
+<!--
+
+   ************************************** WARNING **************************************
+
+   The ciarcom bot parses this header automatically. Any deviation from the 
+   template may cause the bot to automatically correct this header or may result in a 
+   warning message, requesting updates.
+
+   Please ensure that nothing follows the Issue request type section, all 
+   issue details are within the Description section and no changes are made to the 
+   template format (as detailed below).
+
+   *************************************************************************************
+
+-->
+
 ### Description
 
 <!--

CONTRIBUTING.md

@@ -1,45 +1,5 @@
-# Description
-This document is cheat sheet for everyone who wants to contribute to [ARMmbed/mbed-os](https://github.com/ARMmbed/mbed-os) GitHub repository at GitHub. 
-All changes in code base should originate from GitHub Issues and take advantage of existing GitHub flows. Goal is to attract contributors and allow them contribute to code and documentation at the same time.
+# Contributing to Mbed OS
 
-Guidelines from this document are created to help new and existing contributors understand process workflow and align to project rules before pull request is submitted. It explains how a participant should do things like format code, test fixes, and submit patches.
+Mbed OS is an open-source, device software platform for the Internet of Things. Contributions are an important part of the platform, and our goal is to make it as simple as possible to become a contributor.
 
-## Where to get more information?
-You can read more on our [documentation page](https://docs.mbed.com/docs/mbed-os-handbook/en/latest/cont/contributing/).
-
-# How to contribute
-We really appreciate your contributions! We are Open Source project and we need your help. We want to keep it as easy as possible to contribute changes that get things working in your environment. There are a few guidelines that we need contributors to follow so that we can have a chance of keeping on top of things.
-
-Before a pull request will be merged, the [mbed Contributor Agreement](http://developer.mbed.org/contributor_agreement/) must be signed.
-
-You can pick up existing [mbed-os GitHub Issue](https://github.com/ARMmbed/mbed-os/issues) and solve it or implement new feature you find important, attractive or just necessary. We will review your proposal via pull request mechanism, give you comments and merge your changes if we decide your contribution satisfy criteria such as quality.
-
-# Enhancements vs Bugs
-Enhancements are:
-* New features implementation.
-* Code refactoring.
-* Coding rules, coding styles improvements.
-* Code comments improvement.
-* Documentation work.
-
-Bugs are:
-* Issues rose internally or externally by [ARMmbed/mbed-os](https://github.com/ARMmbed/mbed-os) users.
-* Internally (within mbed team) created issues from Continuous Integration pipeline and build servers.
-* Issues detected using automation tools such as compilers, sanitizers, static code analysis tools etc.
-
-# Gate Keeper role
-Gate Keeper is a person responsible for GitHub process workflow execution and is responsible for repository / project code base. Gate Keeper is also responsible for code (pull request) quality stamp and approves or rejects code changes in project’s code base.
-
-Gate Keepers will review your pull request code, give you comments in pull request comment section and in the end if everything goes well merge your pull request to one of our branches (most probably default ```master``` branch).
-
-Please be patient, digest Gate Keeper's feedback and respond promptly :)
-
-# mbed SDK porting
-* For more information regarding mbed SDK porting please refer to [mbed SDK porting](http://developer.mbed.org/handbook/mbed-SDK-porting) handbook.
-* Before starting the mbed SDK porting, you might want to familiarize with the [mbed SDK library internals](http://developer.mbed.org/handbook/mbed-library-internals) first.
-
-# Glossary
-* Gate Keeper – persons responsible for overall code-base quality of [ARMmbed/mbed-os](https://github.com/ARMmbed/mbed-os) project.
-* Enhancement – New feature deployment, code refactoring actions or existing code improvements.
-* Bugfix – Issues originated from GitHub Issues pool, raised internally within mbed classic team or issues from automated code validators like linters, static code analysis tools etc.
-* Mbed classic – mbed SDK 2.0 located in GitHub at [ARMmbed/mbed-os](https://github.com/ARMmbed/mbed-os).
+To encourage productive collaboration, as well as robust, consistent and maintainable code, we have a set of guidelines for contributing to Mbed OS. Please see: [contributing guidelines](https://os.mbed.com/docs/latest/reference/contributing.html).

TESTS/mbed_hal/critical_section/critical_section_test.h

@@ -14,8 +14,11 @@
  * limitations under the License.
  */
 
-/** \addtogroup hal_critical_tests
+/** \addtogroup hal_critical
  *  @{
+ *  \defgroup hal_critical_test Tests 
+ *  Tests definitions of the HAL Critical module.
+ *  @{ 
  */
 
 #ifndef MBED_CRITICAL_SECTION_TEST_H
@@ -45,7 +48,7 @@
 template <int N>
 void test_critical_section();
 
-
+/**@}*/
 /**@}*/
 
 #endif // MBED_CRITICAL_SECTION_TEST_H

TESTS/mbed_hal/qspi/qspi_test.h

@@ -14,8 +14,11 @@
  * limitations under the License.
  */
 
-/** \addtogroup hal_qspi_tests
+/** \addtogroup hal_qspi
  *  @{
+ *  \defgroup hal_qspi_tests Tests
+ *  QSPI tests of the HAL.
+ *  @{ 
  */
 #ifndef MBED_QSPI_TEST_H
 #define MBED_QSPI_TEST_H
@@ -96,3 +99,4 @@ void qspi_write_read_test(void);
 #endif
 
 /** @}*/
+/** @}*/

TESTS/mbed_hal/sleep/sleep_test_utils.h

@@ -15,8 +15,11 @@
  */
 
 /**
- * @addtogroup hal_sleep_test_utils
+ * @addtogroup hal_sleep
  * @{
+ * @defgroup hal_sleep_test_util Tests
+ * Tests of the sleep HAL.
+ * @{     
  */
 
 #ifndef MBED_SLEEP_TEST_UTILS_H
@@ -112,3 +115,4 @@ void lp_ticker_isr(const ticker_data_t *const ticker_data)
 #endif
 
 /** @}*/
+/** @}*/

components/wifi/esp8266-driver/ESP8266Interface.h

@@ -153,36 +153,12 @@ class ESP8266Interface : public NetworkStack, public WiFiInterface
      */
     using NetworkInterface::add_dns_server;
 
-    /** Set 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 handle   Socket handle
-     *  @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 error code on failure
+    /** @copydoc NetworkStack::setsockopt
      */
     virtual nsapi_error_t setsockopt(nsapi_socket_t handle, int level,
             int optname, const void *optval, unsigned optlen);
 
-    /** Get socket options
-     *
-     *  getsockopt allows an application to retrieve stack-specific options
-     *  from the underlying stack using stack-specific level and option names,
-     *  or to request generic options using levels from nsapi_socket_level_t.
-     *
-     *  For unsupported options, NSAPI_ERROR_UNSUPPORTED is returned
-     *  and the socket is unmodified.
-     *
-     *  @param level    Stack-specific protocol level or nsapi_socket_level_t
-     *  @param optname  Level-specific option name
-     *  @param optval   Destination for option value
-     *  @param optlen   Length of the option value
-     *  @return         0 on success, negative error code on failure
+    /** @copydoc NetworkStack::getsockopt
      */
     virtual nsapi_error_t getsockopt(nsapi_socket_t handle, int level, int optname,
             void *optval, unsigned *optlen);

doxyfile_options

@@ -491,7 +491,7 @@ HIDE_UNDOC_CLASSES     = YES
 # included in the documentation.
 # The default value is: NO.
 
-HIDE_FRIEND_COMPOUNDS  = NO
+HIDE_FRIEND_COMPOUNDS  = YES
 
 # If the HIDE_IN_BODY_DOCS tag is set to YES, doxygen will hide any
 # documentation blocks found inside the body of a function. If set to NO, these

doxygen_options.json

@@ -27,6 +27,7 @@
     "HIDE_SCOPE_NAMES": "YES",
     "HIDE_UNDOC_CLASSES": "YES",
     "HIDE_UNDOC_MEMBERS": "YES",
+    "HIDE_FRIEND_COMPOUNDS": "YES",
     "INLINE_INFO": "NO",
     "INLINE_INHERITED_MEMB": "YES",
     "JAVADOC_AUTOBRIEF": "YES",

drivers/MbedCRC.h

@@ -175,7 +175,7 @@ class MbedCRC {
      *
      *  CRC data if not available fully, CRC can be computed in parts with available data.
      *
-     *  In case of hardware, intermediate values and states are saved by hardware and mutex
+     *  In case of hardware, intermediate values and states are saved by hardware. Mutex
      *  locking is used to serialize access to hardware CRC.
      *
      *  In case of software CRC, previous CRC output should be passed as argument to the
@@ -217,7 +217,7 @@ class MbedCRC {
         return status;
     }
 
-    /** Compute partial start, indicate start of partial computation
+    /** Compute partial start, indicate start of partial computation.
      *
      *  This API should be called before performing any partial computation
      *  with compute_partial API.
@@ -257,6 +257,7 @@ class MbedCRC {
      *  This API is used to perform final computation to get correct CRC value.
      *
      *  @param crc  CRC result
+     *  @return  0  on success or a negative in case of failure.
      */
     int32_t compute_partial_stop(uint32_t *crc)
     {
@@ -283,7 +284,7 @@ class MbedCRC {
         return 0;
     }
 
-    /** Get the current CRC polynomial
+    /** Get the current CRC polynomial.
      *
      * @return  Polynomial value
      */
@@ -309,7 +310,7 @@ class MbedCRC {
     uint32_t *_crc_table;
     CrcMode _mode;
 
-    /** Acquire exclusive access to CRC hardware/software
+    /** Acquire exclusive access to CRC hardware/software.
      */
     void lock()
     {
@@ -320,7 +321,7 @@ class MbedCRC {
 #endif
     }
 
-    /** Release exclusive access to CRC hardware/software
+    /** Release exclusive access to CRC hardware/software.
      */
     virtual void unlock()
     {
@@ -331,7 +332,7 @@ class MbedCRC {
 #endif
     }
 
-    /** Get the current CRC data size
+    /** Get the current CRC data size.
      *
      * @return  CRC data size in bytes
      */
@@ -340,7 +341,7 @@ class MbedCRC {
         return (width <= 8 ? 1 : (width <= 16 ? 2 : 4));
     }
 
-    /** Get the top bit of current CRC
+    /** Get the top bit of current CRC.
      *
      * @return  Top bit is set high for respective data width of current CRC
      *          Top bit for CRC width less then 8 bits will be set as 8th bit.
@@ -350,7 +351,7 @@ class MbedCRC {
         return (width < 8 ? (1u << 7) : (uint32_t)(1ul << (width - 1)));
     }
 
-    /** Get the CRC data mask
+    /** Get the CRC data mask.
      *
      * @return  CRC data mask is generated based on current CRC width
      */
@@ -359,7 +360,7 @@ class MbedCRC {
         return (width < 8 ? ((1u << 8) - 1) : (uint32_t)((uint64_t)(1ull << width) - 1));
     }
 
-    /** Final value of CRC is reflected
+    /** Final value of CRC is reflected.
      *
      * @param  data final crc value, which should be reflected
      * @return  Reflected CRC value
@@ -382,7 +383,7 @@ class MbedCRC {
         }
     }
 
-    /** Data bytes are reflected
+    /** Data bytes are reflected.
      *
      * @param  data value to be reflected
      * @return  Reflected data value
@@ -404,7 +405,7 @@ class MbedCRC {
         }
     }
 
-    /** Bitwise CRC computation
+    /** Bitwise CRC computation.
      *
      * @param  buffer  data buffer
      * @param  size  size of the data
@@ -448,7 +449,7 @@ class MbedCRC {
         return 0;
     }
 
-    /** CRC computation using ROM tables
+    /** CRC computation using ROM tables.
     *
     * @param  buffer  data buffer
     * @param  size  size of the data
@@ -493,7 +494,7 @@ class MbedCRC {
         return 0;
     }
 
-    /** Constructor init called from all specialized cases of constructor
+    /** Constructor init called from all specialized cases of constructor.
      *  Note: All construtor common code should be in this function.
      */
     void mbed_crc_ctor(void)