Document Socket API functions return values.

[michalpasztamobica]

Description (required)

Improved the Doxygen documentation of Socket API return values with as much detail as possible, to let user only check the relevant return codes, instead of all nsapi_error_t. Refer to underlying APIs wherever possible.

Once this PR gets reviewed we would like to perform a similar excercise on other APIs. Relevant work item will be created in internal JIRA.

Summary of change (What the change is for and why)

Help API users only check the relevant error codes. Prepare for module tests, which would verify the possible error scenarios, protecting the API from unexpected changes and helping us identify "breaking changes".

Documentation (Details of any document updates required)

This is in fact a documentation update only.

Pull request type (required)

[x] Patch update (Bug fix / Target update / Docs update / Test update / Refactor)
[] Feature update (New feature / Functionality change / New API)
[] Major update (Breaking change E.g. Return code change / API behaviour change)

---

Test results (required)

[x] No Tests required for this change (E.g docs only update)
[] Covered by existing mbed-os tests (Greentea or Unittest)
[] Tests / results supplied as part of this PR

---

Reviewers (optional)

@AnttiKauppila
@tymoteuszblochmobica
@mtomczykmobica

---

[michalpasztamobica]

I just realized that there were InternetDatagramSocket and ICMPSocket added in the meantime. I need to resolve the conflicts and update doxygen in those two classes as well.

[0xc0170]

@michalpasztamobica Please rebase to resolve conflict

[michalpasztamobica]

@0xc0170 , rebased and conflicts resolved.

[0xc0170]

CI started

[0xc0170]

Travis found one issue in doxygen: "authetication" - please fix

[michalpasztamobica]

@0xc0170 , fixed :)

[mbed-ci]

Test run: FAILED

Summary: 3 of 4 test jobs failed
Build number : 1
Build artifacts

Failed test jobs:

• jenkins-ci/mbed-os-ci_build-IAR
• jenkins-ci/mbed-os-ci_build-ARM
• jenkins-ci/mbed-os-ci_build-GCC_ARM

[0xc0170]

CI restarted (aborted above)

[mbed-ci]

Test run: FAILED

Summary: 1 of 11 test jobs failed
Build number : 2
Build artifacts

Failed test jobs:

• jenkins-ci/mbed-os-ci_cloud-client-pytest

[michalpasztamobica]

I don't think the failure is related:

[2019-11-04T12:49:37.983Z] [2019-11-04T12:49:37.983Z] --- Logging error ---
[2019-11-04T12:49:37.983Z] [2019-11-04T12:49:37.983Z] Traceback (most recent call last):
[2019-11-04T12:49:37.983Z] [2019-11-04T12:49:37.983Z]   File "/usr/lib/python3.6/logging/__init__.py", line 996, in emit
[2019-11-04T12:49:37.983Z] [2019-11-04T12:49:37.983Z]     stream.write(msg)
[2019-11-04T12:49:37.983Z] [2019-11-04T12:49:37.983Z]   File "/usr/local/lib/python3.6/dist-packages/_pytest/capture.py", line 427, in write
[2019-11-04T12:49:37.983Z] [2019-11-04T12:49:37.983Z]     self.buffer.write(obj)
[2019-11-04T12:49:37.983Z] [2019-11-04T12:49:37.983Z] ValueError: I/O operation on closed file
[2019-11-04T12:49:37.983Z] [2019-11-04T12:49:37.983Z] Call stack:
[2019-11-04T12:49:37.983Z] [2019-11-04T12:49:37.983Z]   File "/usr/local/lib/python3.6/dist-packages/socketIO_client-0.7.7-py3.6.egg/socketIO_client/__init__.py", line 390, in __del__
[2019-11-04T12:49:37.983Z] [2019-11-04T12:49:37.983Z]     self.disconnect()
[2019-11-04T12:49:37.983Z] [2019-11-04T12:49:37.983Z]   File "/usr/local/lib/python3.6/dist-packages/socketIO_client-0.7.7-py3.6.egg/socketIO_client/__init__.py", line 438, in disconnect
[2019-11-04T12:49:37.983Z] [2019-11-04T12:49:37.983Z]     namespace._find_packet_callback('disconnect')()
[2019-11-04T12:49:37.983Z] [2019-11-04T12:49:37.983Z]   File "/usr/local/lib/python3.6/dist-packages/raas_client-0.12.0-py3.6.egg/raas_client/api/socketio.py", line 356, in _sio_disconnect
[2019-11-04T12:49:37.983Z] [2019-11-04T12:49:37.983Z]     self.logger.warning('socketio disconnect event received')
[2019-11-04T12:49:37.983Z] [2019-11-04T12:49:37.983Z] Message: 'socketio disconnect event received'
[2019-11-04T12:49:37.983Z] [2019-11-04T12:49:37.983Z] Arguments: ()
[2019-11-04T12:49:39.614Z] [2019-11-04T12:49:39.614Z] Terminated

@0xc0170 , I only changed Doxygen documentation. Does it make sense to run the whole CI?

[0xc0170]

I restarted cloud test

[0xc0170]

As these are small corrections to return values, I'll merge this today.

@AnotherButler If any change requested , will be addressed separately.

[adbridge]

This contains changes on top of #11357 which is targeting 5.15