remove internally used functionality from public API documentation (#973

)

Versioning.md

@@ -65,6 +65,10 @@ Refer to the [ABI Policy](./docs/abi-policy.md) for more details. To summarise:
   allowed to break existing stable interfaces. Feature flags will be removed
   once we have a stable implementation for the signal.
 
+* Code under the "*::detail" namespace implements internal details,
+  and NOT part of public interface. Also, any API not documented in the [public
+  documentation](https://opentelemetry-cpp.readthedocs.io/en/latest/) is NOT part of public interface.
+
 * GitHub releases will be made for all released versions.
 
 ## Example Versioning Lifecycle

api/include/opentelemetry/common/key_value_iterable_view.h

@@ -14,6 +14,8 @@
 OPENTELEMETRY_BEGIN_NAMESPACE
 namespace common
 {
+// NOTE - code within `detail` namespace implements internal details, and not part
+// of the public interface.
 namespace detail
 {
 inline void take_key_value(nostd::string_view, common::AttributeValue) {}

api/include/opentelemetry/detail/preprocessor.h

@@ -1,6 +1,9 @@
 // Copyright The OpenTelemetry Authors
 // SPDX-License-Identifier: Apache-2.0
 
+// NOTE - code within detail namespace implements internal details, and not part
+// of the public interface.
+
 #pragma once
 
 #define OPENTELEMETRY_STRINGIFY(S) OPENTELEMETRY_STRINGIFY_(S)

api/include/opentelemetry/trace/propagation/detail/hex.h

@@ -13,6 +13,8 @@ namespace trace
 {
 namespace propagation
 {
+// NOTE - code within `detail` namespace implements internal details, and not part
+// of the public interface.
 namespace detail
 {
 

api/include/opentelemetry/trace/propagation/detail/string.h

@@ -10,6 +10,8 @@ namespace trace
 {
 namespace propagation
 {
+// NOTE - code within `detail` namespace implements internal details, and not part
+// of the public interface.
 namespace detail
 {
 

api/include/opentelemetry/trace/span_context_kv_iterable_view.h

@@ -15,6 +15,8 @@
 OPENTELEMETRY_BEGIN_NAMESPACE
 namespace trace
 {
+// NOTE - code within `detail` namespace implements internal details, and not part
+// of the public interface.
 namespace detail
 {
 template <class T>

docs/public/Doxyfile

@@ -848,6 +848,7 @@ EXCLUDE                = ../../api/include/opentelemetry/common/spin_lock_mutex.
                          ../../api/include/opentelemetry/common/kv_properties.h \
                          ../../api/include/opentelemetry/common/string_util.h \
                          ../../api/include/opentelemetry/trace/span_context_kv_iterable_view.h \
+                         ./../api/include/opentelemetry/trace/propagation/detail \
                          ../../api/include/opentelemetry/nostd
 
 # The EXCLUDE_SYMLINKS tag can be used to select whether or not files or