Fix documentation

Author: ocelotl

opentelemetry-api/src/opentelemetry/configuration/__init__.py

@@ -74,9 +74,18 @@
 
 To use the meter provider above, then the
 ``OPENTELEMETRY_PYTHON_METER_PROVIDER`` should be set to
-"default_meter_provider" (this is not actually necessary since the
+``"default_meter_provider"`` (this is not actually necessary since the
 OpenTelemetry API provided providers are the default ones used if no
 configuration is found in the environment variables).
+
+This object can be used by any OpenTelemetry component, native or external.
+For that reason, the ``Configuration`` object is designed to be immutable.
+If a component would change the value of one of the ``Configuration`` object
+attributes then another component that relied on that value may break, leading
+to bugs that are very hard to debug. To avoid this situation, the preferred
+approach for components that need a different value than the one provided by
+the ``Configuration`` object is to implement a mechanism that allows the user
+to override this value instead of changing it.
 """
 
 from os import environ

opentelemetry-auto-instrumentation/src/opentelemetry/auto_instrumentation/instrumentor.py

@@ -64,18 +64,13 @@ def instrument(self, **kwargs):
         mechanism) that will be used later by the code in the ``instrument``
         implementation via the global ``Configuration`` object.
 
-        When this method is to be called directly in the user code, ``kwargs``
-        should be used to pass attributes that will override the configuration
-        values read by the ``Configuration`` object.
-
-        In this way, calling this method directly without passing any optional
-        values should do the very same thing that the
-        ``opentelemetry-auto-instrumentation`` command does. The idea behind
-        this approach is also to keep the ``Configuration`` object immutable.
-
-        This is necessary because this object is used by all the OpenTelemetry
-        components and any change to one of its attributes could break another
-        component, leading to very hard to debug bugs.
+        The ``instrument`` methods ``kwargs`` should default to values from the
+        ``Configuration`` object.
+
+        This means that calling this method directly without passing any
+        optional values should do the very same thing that the
+        ``opentelemetry-auto-instrumentation`` command does. This approach is
+        followed because the ``Configuration`` object is immutable.
         """
 
         if not self._is_instrumented:
@@ -88,7 +83,11 @@ def instrument(self, **kwargs):
         return None
 
     def uninstrument(self, **kwargs):
-        """Uninstrument the library"""
+        """Uninstrument the library
+
+        See ``BaseInstrumentor.instrument`` for more information regarding the
+        usage of ``kwargs``.
+        """
 
         if self._is_instrumented:
             result = self._uninstrument(**kwargs)