diff --git a/Doc/library/filecmp.rst b/Doc/library/filecmp.rst
--- a/Doc/library/filecmp.rst
+++ b/Doc/library/filecmp.rst
@@ -13,6 +13,14 @@
 with various optional time/correctness trade-offs. For comparing files,
 see also the :mod:`difflib` module.
 
+Module Interface
+----------------
+
+.. data:: BUFSIZE
+
+   The buffer size value which will be used to read the file contents. Defaults
+   to 8192 bytes.
+
 The :mod:`filecmp` module defines the following functions:
 
 
@@ -21,11 +29,15 @@
    Compare the files named *f1* and *f2*, returning ``True`` if they seem equal,
    ``False`` otherwise.
 
-   Unless *shallow* is given and is false, files with identical :func:`os.stat`
-   signatures are taken to be equal.
+   The *shallow* flag, which defaults to True, enforces only :func:`os.stat`
+   values of files to be compared and file contents are not read.
 
-   Files that were compared using this function will not be compared again unless
-   their :func:`os.stat` signature changes.
+   When *shallow* flag is set to False, :data:`filecmp.BUFSIZE` bytes of file
+   content will be read and compared.
+
+   This function uses a cache for past comparisons and results. Files that were
+   compared using this function will not be compared again unless their
+   :func:`os.stat` signature changes.
 
    Note that no external programs are called from this function, giving it
    portability and efficiency.
@@ -68,34 +80,37 @@
 :class:`dircmp` instances are built using this constructor:
 
 
-.. class:: dircmp(a, b, ignore=None, hide=None)
+.. class:: dircmp(dir1, dir2, ignore=None, hide=None)
 
-   Construct a new directory comparison object, to compare the directories *a* and
-   *b*. *ignore* is a list of names to ignore, and defaults to ``['RCS', 'CVS',
-   'tags']``. *hide* is a list of names to hide, and defaults to ``[os.curdir,
-   os.pardir]``.
+   Construct a new directory comparison object, to compare the directories
+   *dir1* and *dir2*. *ignore* is a list of names to ignore, and defaults to
+   ``['RCS', 'CVS', 'tags']``. *hide* is a list of names to hide, and defaults
+   to ``[os.curdir, os.pardir]``.
+
+   The :class:`dircmp` class compares files by doing *shallow* comparisons as
+   described for :func:`filecmp.cmp`.
 
    The :class:`dircmp` class provides the following methods:
 
 
    .. method:: report()
 
-      Print (to ``sys.stdout``) a comparison between *a* and *b*.
+      Print (to ``sys.stdout``) a comparison between *dir1* and *dir2*.
 
 
    .. method:: report_partial_closure()
 
-      Print a comparison between *a* and *b* and common immediate
+      Print a comparison between *dir1* and *dir2* and common immediate
       subdirectories.
 
 
    .. method:: report_full_closure()
 
-      Print a comparison between *a* and *b* and common subdirectories
+      Print a comparison between *dir1* and *dir2* and common subdirectories
       (recursively).
 
-   The :class:`dircmp` offers a number of interesting attributes that may be
-   used to get various bits of information about the directory trees being
+   The :class:`dircmp` class offers a number of interesting attributes that may
+   be used to get various bits of information about the directory trees being
    compared.
 
    Note that via :meth:`__getattr__` hooks, all attributes are computed lazily,
@@ -105,58 +120,60 @@
 
    .. attribute:: left_list
 
-      Files and subdirectories in *a*, filtered by *hide* and *ignore*.
+      Files and subdirectories in *dir1*, filtered by *hide* and *ignore*.
 
 
    .. attribute:: right_list
 
-      Files and subdirectories in *b*, filtered by *hide* and *ignore*.
+      Files and subdirectories in *dir2*, filtered by *hide* and *ignore*.
 
 
    .. attribute:: common
 
-      Files and subdirectories in both *a* and *b*.
+      Files and subdirectories in both *dir1* and *dir2*.
 
 
    .. attribute:: left_only
 
-      Files and subdirectories only in *a*.
+      Files and subdirectories only in *dir1*.
 
 
    .. attribute:: right_only
 
-      Files and subdirectories only in *b*.
+      Files and subdirectories only in *dir2*.
 
 
    .. attribute:: common_dirs
 
-      Subdirectories in both *a* and *b*.
+      Subdirectories in both *dir1* and *dir2*, using the class's file
+      comparison operator.
 
 
    .. attribute:: common_files
 
-      Files in both *a* and *b*
+      Files in both *dir1* and *dir2*, whose contents differ according to the
+      class's file comparison operator.
 
 
    .. attribute:: common_funny
 
-      Names in both *a* and *b*, such that the type differs between the
+      Names in both *dir1* and *dir2*, such that the type differs between the
       directories, or names for which :func:`os.stat` reports an error.
 
 
    .. attribute:: same_files
 
-      Files which are identical in both *a* and *b*.
+      Files which are identical in both *dir1* and *dir2*.
 
 
    .. attribute:: diff_files
 
-      Files which are in both *a* and *b*, whose contents differ.
+      Files which are in both *dir1* and *dir2*, whose contents differ.
 
 
    .. attribute:: funny_files
 
-      Files which are in both *a* and *b*, but could not be compared.
+      Files which are in both *dir1* and *dir2*, but could not be compared.
 
 
    .. attribute:: subdirs
@@ -164,3 +181,21 @@
       A dictionary mapping names in :attr:`common_dirs` to :class:`dircmp`
       objects.
 
+
+An example usage::
+
+    import argparse
+    import filecmp
+
+    if __name__ == '__main__':
+        parser = argparse.ArgumentParser(description="Directory comparison")
+        parser.add_argument("--recurse", "-r", action="store_true", default=False)
+        parser.add_argument('dirs', nargs=2)
+        options = parser.parse_args()
+
+        dd = filecmp.dircmp(options.dirs[0], options.dirs[1])
+
+        if options.recurse:
+            dd.report_full_closure()
+        else:
+            dd.report()