Make clearer distinction between public and private API for `iceoryx_hoofs`

[mossmaurice]

Brief feature description

The current distinction between public and private API on namespace and folder level can be confusing for developers.

Detailed information

1. Namespace
   1. From a user perspective every class or construct shall only have one iox:: namespace, no matter if private or public API. This will allow users an easier transition once a private API has stabilized and will become public.
   2. Stuff in the detail namespace is an implementation detail
   3. detail (16 hits) and internal (91 hits) namespaces are equivalent
      1. Fix this before the v3.0 release, only using detail
   4. Add an entry in CONTRIBUTING.md#naming-conventions
2. Folder
   1. Everything in #include "iox/.." is part of the public API
   2. Everything in #include "iox/detail/.." is part of the private API and can be used at your own risk, e.g. we can use the unique_id in posh
   3. Add an entry in CONTRIBUTING.md#folder-structure
3. iceoryx_hoofs/Readme.md
   1. Don't exposed in the private user API in the documentation (e.g. iceoryx_hoofs/Readme.md). As a result we communicate clearer what is public and what is private, a thing where we haven't been super clear before.

References

• From this comment

[elBoberido]

@mossmaurice after you left the meeting we basically agreed on the proposal from the description. Everything with an iox/detail/ include and iox::detail is not public API.

Larger components might have an additional namespace to group structs/classes with a generic name. Currently those components are cli, log, error, units and concurrent. These will append the detail namespace to their second level namespace, e.g. iox::concurrent::detail.

Additional namespaces should be avoided but can be used when it simplifies the usage or makes the user aware of specific capabilities, like components in iox::concurrent are thread safe or iox::log::hex can be used to format the log output in hexadecimal format.

More than two namespaces for classes intended to be used by the end user should be avoided by now but can be re-considered at a later point in time.

This needs to be documented in CONTRIBUTING.md

cc @FerdinandSpitzschnueffler @elfenpiff