Update catalog docs

docs/catalogs/index.rst

@@ -4,35 +4,34 @@ Catalogs
 Catalogs are collections of providers. Main purpose of catalogs is to group
 providers. 
 
-There are, actually, several popular use cases of catalogs:
+There are, actually, several popular cases of catalogs usage:
 
-- Grouping of providers from same architectural layer (for example, 
+- Grouping of providers from the same architectural layer (for example, 
   ``Services``, ``Models`` and ``Forms`` catalogs).
-- Grouping of providers from a same functional components (for example,
+- Grouping of providers from the same functional groups (for example,
   catalog ``Users``, that contains all functional parts of ``Users``
   component).
 
-Als, for both of these and some other cases, it might be useful to attach 
+Also, for both of these and some other cases, it might be useful to attach 
 some init / shutdown functionality or something else, that deals with group 
 of providers.
 
 Writing catalogs
 ----------------
 
-Catalogs have to be created by extending base catalog class 
+Catalogs have to extend base catalog class ``di.AbstractCatalog``.
-``dependency_injector.catalog.AbstractCatalog``.
 
 Providers have to be defined like catalog's attributes. Every provider in
-catalog has name. This name should follow ``some_provider`` manner, that is 
+catalog has name. This name should follow ``some_provider`` convention, 
-standard naming convention for names of attributes in Python.
+that is standard naming convention for attribute names in Python.
 
 .. note::
 
-    It might be useful to add such 
+    It might be useful to add such ``""":type: (di.Provider) -> Object1"""`` 
-    ``""":type: (dependency_injector.Provider) -> Object1"""`` documentation 
+    documentation blocks one line after provider definition for every provider.
-    blocks one line after provider definition for every provider. It will help 
+    It will help code analyzing tools and IDE's to understand that variable 
-    code analysis tools and IDE's to understand that variable above contains 
+    above contains some callable object, that returns particular instance 
-    some callable object, that returns particular instance as a result of call.
+    in a result of call.
 
 Example:
 
@@ -49,13 +48,13 @@ Operating with catalog providers
 There are several things that could be useful for operating with catalog
 providers:
 
-- First of all, ``Catalog.providers`` attribute contains ``dict`` with all
+- First of all, ``di.AbstractCatalog.providers`` attribute contains ``dict`` 
-  catalog providers and their catalog names. This dictionary could be used
+  with all catalog providers. This dictionary could be used for any kind of 
-  for any kind of operations that could be done with providers. The only note,
+  operations that could be done with providers. The only note, is that 
-  is that ``Catalog.providers`` attribute is read-only.
+  ``di.AbstractCatalog.providers`` attribute is read-only.
-- Second one, ``Catalog.filter(provider_type=Provider)`` method could be
+- Second one, ``di.AbstractCatalog.filter(provider_type=di.Provider)`` method 
-  used for filtering catalog providers by provider types (for example, for 
+  could be used for filtering catalog providers by provider types (for example,
-  getting all ``Factory`` providers).
+  for getting all ``di.Factory`` providers).
 
 Example:
 
@@ -71,15 +70,15 @@ same names in overridden catalog.
 
 There are two ways to override catalog by another catalog:
 
-- Use ``Catalog.override(Catalog)`` method.
+- Use ``di.AbstractCatalog.override(AnotherCatalog)`` method.
-- Use ``@override(Catalog)`` class decorator.
+- Use ``@di.override(AnotherCatalog)`` class decorator.
 
-Example of overriding catalog using ``Catalog.override()`` method:
+Example of overriding catalog using ``di.AbstractCatalog.override()`` method:
 
 .. literalinclude:: ../../examples/catalogs/override.py
    :language: python
 
-Example of overriding catalog using ``@override()`` decorator:
+Example of overriding catalog using ``@di.override()`` decorator:
 
 .. literalinclude:: ../../examples/catalogs/override_decorator.py
    :language: python

examples/catalogs/override.py

@@ -1,4 +1,4 @@
-"""`Catalog.override()` example."""
+"""Catalog overriding example."""
 
 import collections
 import dependency_injector as di

examples/catalogs/override_decorator.py

@@ -1,4 +1,4 @@
-"""Catalog `@override()` decorator example."""
+"""Catalog overriding using `@di.override()` decorator example."""
 
 import collections
 import dependency_injector as di