Re: [PATCH 06/11] MyFirstObjectWalk: update recommended usage

From: Derrick Stolee <derrickstolee@github.com>
Date: Mar 7, 2022, 14:05 UTC
Message-ID: <e163a286-37cb-2568-1d96-0c7b7fba4e5a@github.com>
In-Reply-To: <xmqqtucdxs8x.fsf@gitster.g>

On 3/4/2022 5:33 PM, Junio C Hamano wrote:

> "Derrick Stolee via GitGitGadget" <gitgitgadget@gmail.com> writes:

Show 18 quoted lines

>>  the name, these functions traverse all kinds of objects. Let's have a look at
>> -the arguments to `traverse_commit_list_filtered()`, which are a superset of the
>> -arguments to the unfiltered version.
>> +the arguments to `traverse_commit_list()`.
>>  
>> -- `struct list_objects_filter_options *filter_options`: This is a struct which
>> -  stores a filter-spec as outlined in `Documentation/rev-list-options.txt`.
>> -- `struct rev_info *revs`: This is the `rev_info` used for the walk.
>> +- `struct rev_info *revs`: This is the `rev_info` used for the walk. It
>> +  includes a `filter` member which contains information for how to filter
>> +  the object list.
> 
> Perhaps,
> 
>     "When its `filter` member is not NULL, it contains ..."
> 
> implying that it is valid for `filter` member to be NULL and none of
> the following things will happen in such a case.

Definitely room for improvement here. I got hung up on the two uses of "it" so here is another attempt:

 If its `filter` member is not `NULL`, then `filter` contains
 information for how to filter the object list.

What do you think?

Thanks, -Stolee