Merge pull request #305 from palazzem/update-docs

[docs] be more explicit in docs

Author: Emanuele Palazzetti

ddtrace/contrib/asyncio/__init__.py

@@ -36,7 +36,8 @@ async def some_work():
       are attached to the main trace
 
 A ``patch(asyncio=True)`` is available if you want to automatically use above
-wrappers without changing your code.
+wrappers without changing your code. In that case, the patch method **must be
+called before** importing stdlib functions.
 """
 from ..util import require_modules
 

ddtrace/contrib/django/__init__.py

@@ -1,9 +1,10 @@
 """
 The Django integration will trace requests, database calls and template
-renders.
+renderers.
 
-To install the Django tracing middleware, add it to the list of your
-installed apps and in your middleware classes in ``settings.py``::
+To enable the Django integration, add the application to your installed
+apps and our tracing middleware **as a first middleware** in your ``MIDDLEWARE``
+list, as follows::
 
     INSTALLED_APPS = [
         # your Django apps...
@@ -13,23 +14,22 @@
     ]
 
     # or MIDDLEWARE_CLASSES for Django pre 1.10
-    MIDDLEWARE = (
+    MIDDLEWARE = [
         # the tracer must be the first middleware
         'ddtrace.contrib.django.TraceMiddleware',
 
         # your middlewares...
-    )
+    ]
 
-The configuration of this integration is all namespaced inside a single
-Django setting, named ``DATADOG_TRACE``. For example, your ``settings.py``
-may contain::
+The configuration for this integration is namespaced under the ``DATADOG_TRACE``
+Django setting. For example, your ``settings.py`` may contain::
 
     DATADOG_TRACE = {
         'DEFAULT_SERVICE': 'my-django-app',
         'TAGS': {'env': 'production'},
     }
 
-If you need to access to the tracing settings, you should::
+If you need to access to integration settings, you should::
 
     from ddtrace.contrib.django.conf import settings
 

ddtrace/contrib/gevent/__init__.py

@@ -6,7 +6,7 @@
 yield the context to another one.
 
 The simplest way to trace a ``gevent`` application is to configure the tracer and
-patch ``gevent`` before using it::
+patch ``gevent`` **before importing** the library::
 
     # patch before importing gevent
     from ddtrace import patch, tracer

ddtrace/contrib/sqlalchemy/__init__.py

@@ -1,6 +1,6 @@
 """
-To trace sqlalchemy queries, add instrumentation to the engine class or
-instance you are using::
+To trace sqlalchemy queries, add instrumentation to the engine class
+using the patch method that **must be called before** importing sqlalchemy::
 
     # patch before importing `create_engine`
     from ddtrace import Pin, patch

ddtrace/contrib/tornado/__init__.py

@@ -1,7 +1,9 @@
 """
 The Tornado integration traces all ``RequestHandler`` defined in a Tornado web application.
-Auto instrumentation is available using the ``patch`` function as follows::
+Auto instrumentation is available using the ``patch`` function that **must be called before**
+importing the tornado library. The following is an example::
 
+    # patch before importing tornado
     from ddtrace import tracer, patch
     patch(tornado=True)
 

ddtrace/span.py

@@ -152,8 +152,10 @@ def set_metas(self, kvs):
         self.set_tags(kvs)
 
     def set_metric(self, key, value):
-        # FIXME[matt] we could push this check to serialization time as well.
+        # This method sets a numeric tag value for the given key. It acts
+        # like `set_meta()` and it simply add a tag without further processing.
 
+        # FIXME[matt] we could push this check to serialization time as well.
         # only permit types that are commonly serializable (don't use
         # isinstance so that we convert unserializable types like numpy
         # numbers)

docs/index.rst

@@ -37,7 +37,7 @@ for changing your code::
     Usage: [ENV_VARS] ddtrace-run <my_program>
 
 
-The available environment settings are:
+The available environment variables are:
 
 * ``DATADOG_TRACE_ENABLED=true|false`` (default: true): Enable web framework and library instrumentation. When false, your application code
   will not generate any traces.