Add Secure socket documentations

[SeppoTakalo]

Add documentation about Secure Socket.

Class references cannot yet be added, because implementation PR just submitted in ARMmbed/mbed-os#8311

@AnotherButler please review.

This documentation has already been technically reviewed by @kjbracey-arm in external repository.

[AnotherButler]

This doesn't follow our usual structure. Should we move some of this content into architecture and configuration?

[AnotherButler]

@SeppoTakalo Please rearrange, so the description is at the beginning, and the examples come at the end.

[AnotherButler]

This page still needs to be arranged to match our standard template.

[SeppoTakalo]

I'll start to work on this within this sprint.

[AnotherButler]

What's the status of this?

[AnotherButler]

This PR is waiting on content rearrangement to match our other APIs.

[SeppoTakalo]

@AnotherButler I moved the generic design part under the "reference" book and created simpler TLSSocket.md and DTLSSocket.md pages that follow the content of other API documents.

[SeppoTakalo]

I noticed that Doxygen have not parsed the TLSSocket classes, so I have fixed those now.
I also added the DTLSSocket documentation, so this have now code dependency to ARMmbed/mbed-os#8659

[AnotherButler]

Nice work on this, @SeppoTakalo 👍 It looks great

[AnotherButler]

Update: This PR is only waiting on the code dependency to make the Doxygen work.

[SeppoTakalo]

@AnotherButler Code has now been merged. This PR can also be merged now.

[MarceloSalazar]

Can we add an example that showcases a Secure TLS socket connection?

Also, would you consider adding a tutorial based on this content, which is really useful?
https://os.mbed.com/blog/entry/Adding-TLS-Sockets-to-Mbed-OS/

[AnotherButler]

@MarceloSalazar As long as the code is still up to date, I'm happy to convert the content into a new tutorial. However, that's out of scope of this PR and won't happen for code freeze. Could you please create a new task for that?

[SeppoTakalo]

@MarceloSalazar There is an example, embedded in the documentation.

https://github.com/ARMmbed/mbed-os-5-docs/blob/971b190dade931241625ed20b1e811ca1fc62e81/docs/api/networksocket/TLSSocket.md

Just click the "View Program button" and it leads to the example.

https://github.com/ARMmbed/mbed-os-examples-docs_only/blob/master/TLSSocket/main.cpp

When documentation is rendered, this would be the "Import program" button.

[MarceloSalazar]

@AnotherButler no problem, I'm not expecting the content from the blog to land in docs for 5.11.0.
I've created ticket IOTDOCS-806 to keep track of the request and consider doing this when appropiate.

@SeppoTakalo thanks for the link to the example. It looks relatively simple (not too many lines of code :)
At the same time, I feel users of this example are missing some context. For example:

• What do I need to get started?
• What hardware and connectivity are supported?
• Where do I get the certificate from?
  As we don't have markdown file (as github), maybe this info could be added to the docs on os.mbed.com?

On a separate note (also FYI @adbridge):

• How do you expect us to evaluate this example during OOB?
• Is this following the process that let the internal team to create a OOB branch for 5.11-RC1 and use this for both Mbed CLI and the Online Compiler?

[adbridge]

@MarceloSalazar As this is not an official mbed-os-example then it won't be updated in the same way we do for other examples for OOB. Onus will be on the example owner ie @SeppoTakalo to make sure this is ready and suitable.

[AnotherButler]

Is this ready to merge?

[SeppoTakalo]

Yes