bug#40202: directory-files-recursively docstring unclear about include-directories

[Arun Isaac <arunisaac@systemreboot.net>]

[-- Attachment #1: Type: text/plain, Size: 1428 bytes --]


>> The docstring of directory-file-recursively in lisp/files.el is unclear
>> about the include-directories optional argument. It currently reads
>> 
>> "Optional argument INCLUDE-DIRECTORIES non-nil means also include
>> in the output directories whose names match REGEXP."
>> 
>> Perhaps this could be rewritten as
>> 
>> "If optional argument INCLUDE-DIRECTORIES is non-nil, the returned list
>> also includes directories whose names match REGEXP."
>
> Could you please explain which part(s) of the proposed doc string make
> the issue more clear for you?  To me both variants sound equivalent.

They seem equivalent once you already know the meaning that is supposed
to be conveyed. I had to wrack my brains for a while before I understood
what that sentence means.

1. It is not immediately clear how to parse the original docstring. Is
it parsed as "(include) (in the output directories whose name matches
REGEXP)", "(include in the output directories) (whose name matches
REGEXP)" or "(include in the output) (directories whose name matches
REGEXP)"? The phrase "in the output" in between the sentence makes it
difficult to parse. Some punctuation there could have helped, but I
don't see how to do that.

2. The grammar of my proposal is better. In the original, the usage of
"means" as the predicate, "optional argument INCLUDE-DIRECTORIES
non-nil" as the subject is unusual and awkward.

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 487 bytes --]