The documentation for the dircmp class doesn't say that the same_files and diff_files attributes are determined using the "shallow=True" rules described in the filecmp.cmp() and filecmp.cmpfiles().  It should say this.

For example, the documentation describes diff_files as, "Files which are in both a and b, whose contents differ."  But this isn't true since files whose contents differ aren't included if their os.stat() signatures are equal.

See also issue 12932 to allow dircmp to perform non-shallow comparisons.

Thanks for this report. I saw that filecmp.rst could be improved a bit further too. I added some additional improvements to the docs in addition to the one you mentioned in the patch.

For attribution purposes and to keep the issue focused, shouldn't those other changes be added as part of a separate issue?

The changes you added are much larger than mine, and address cosmetic issues and other issues unrelated to the original point about dircmp comparisons being "shallow".

If by attribution, if you mean, proper mention of credits/ acks, during the
commit, I shall add it. Also, I agree that "shallow" should be documented.
But there were few more places which were lacking, so I ended up with
expanding docs after reading the code. I can commit in two phases, if it is
desired or commit yours and then make the other  documentation
improvements. Thanks!

Thanks, Senthil.  I would prefer if you created a new issue in the tracker for your additional changes, and then committed your changes as part of that issue.  By attribution, I was referencing the "Patch by Chris Jerdonek" which can go in the commit message and Misc/NEWS for this issue.  I am already listed in Misc/ACKS.

To keep things simple, can you perhaps review my original patch as is?  If you would like, I would be happy to provide feedback separately on your own changes.

Hi Chris, your patch looks good. I shall commit it now. The rest of the documentation changes can go in another patch. Thanks!

New changeset f6ce142c2fce by Senthil Kumaran in branch '3.2':
- Issue #15250: Document that filecmp.dircmp compares files shallowly. Patch contributed by Chris Jerdonek.
http://hg.python.org/cpython/rev/f6ce142c2fce

New changeset d2a49ee77b6f by Senthil Kumaran in branch 'default':
- Issue #15250: Document that filecmp.dircmp compares files shallowly. Patch contributed by Chris Jerdonek.
http://hg.python.org/cpython/rev/d2a49ee77b6f

New changeset 3921d3c71e64 by Senthil Kumaran in branch '2.7':
Issue #15250: Document that filecmp.dircmp compares files shallowly. Patch contributed by Chris Jerdonek.
http://hg.python.org/cpython/rev/3921d3c71e64

This is taken care. Rest of documentation improvements could be dealt with in Issue15430. Thanks, Chris.

Thanks a lot for committing this for me Senthil.  And thanks also for creating a separate issue for the other changes.  I appreciate it.