classification
Title: Improve filecmp documentation
Type: behavior Stage: resolved
Components: Documentation Versions:
process
Status: closed Resolution: rejected
Dependencies: Superseder:
Assigned To: orsenthil Nosy List: chris.jerdonek, orsenthil
Priority: normal Keywords: easy, patch

Created on 2012-07-23 02:39 by orsenthil, last changed 2016-01-09 05:39 by orsenthil. This issue is now closed.

Files
File name Uploaded Description Edit
Issue15250.patch orsenthil, 2012-07-23 02:39
Messages (3)
msg166200 - (view) Author: Senthil Kumaran (orsenthil) * (Python committer) Date: 2012-07-23 02:39
filecmp.rst could see some improvements which are easy and useful too. It was discussed in Issue15250 and a patch is attached.
msg166205 - (view) Author: Chris Jerdonek (chris.jerdonek) * (Python committer) Date: 2012-07-23 04:18
Some comments on the patch:

+   The buffer size value which will be used to read the file contents. Defaults
+   to 8192 bytes.

I would consider including the units for the value here (e.g. "The buffer
size value in bytes...").

+   When *shallow* flag is set to False, :data:`filecmp.BUFSIZE` bytes of file
+   content will be read and compared.

Should this instead read something like, "When the *shallow* flag is set to
False, the file contents will be read and compared, reading
:data:`filecmp.BUFSIZE` bytes at a time."  The current wording suggests
that only the first BUFSIZE bytes will be looked at.

+   The :class:`dircmp` class compares files by doing *shallow* comparisons as
+   described for :func:`filecmp.cmp`.

This change was already committed as part of issue 15250.

+   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

This change was already committed as part of issue 15250.

    .. attribute:: common_dirs

-      Subdirectories in both *a* and *b*.
+      Subdirectories in both *dir1* and *dir2*, using the class's file
+      comparison operator.

The phrase "using the class's file comparison operator" should not be added
to common_dirs.  common_dirs does not look at file contents.

    .. 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.

The phrase "whose contents differ according to the class's file comparison
operator" should not be added to common_files.  common_files does not look
at file contents.

    .. attribute:: same_files

-      Files which are identical in both *a* and *b*.
+      Files which are identical in both *dir1* and *dir2*.

This line should reflect the change committed for issue 15250.

    .. 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.

This line should reflect the change committed for issue 15250.
msg257797 - (view) Author: Senthil Kumaran (orsenthil) * (Python committer) Date: 2016-01-09 05:39
This bug report can be closed as the patch, written by me is no longer valid. 
The only useful addition it can bring is, exposing the BUFSIZE, but that is used transparently by the module and I think, it need not be exposed via documentation.
History
Date User Action Args
2016-01-09 05:39:12orsenthilsetstatus: open -> closed
resolution: rejected
messages: + msg257797

stage: patch review -> resolved
2012-07-23 04:18:44chris.jerdoneksetmessages: + msg166205
2012-07-23 02:39:30orsenthilcreate