Issue 15430: Improve filecmp documentation (original) (raw)

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.

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.