attr: fix instructions on how to check attrs

Commit Message

John Cai Jan. 22, 2023, 3:06 a.m. UTC

From: John Cai <[e-mail]>

The instructions in attr.h describing what functions to call to check
attributes is missing the index as the first argument to git_check_attr.

Fix this to make it consistent with the actual function signature.

Signed-off-by: John Cai <[e-mail]>
---
    attr: fix instructions on how to check attrs
    
    The instructions in attr.h describing what functions to call to check
    attributes is missing the index as the first argument to git_check_attr.
    
    Fix this to make it consistent with the actual function signature.
    
    Signed-off-by: John Cai [e-mail]

Published-As: https://github.com/gitgitgadget/git/releases/tag/pr-git-1441%2Fjohn-cai%2Fjc%2Ffix-attr-docs-v1
Fetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-git-1441/john-cai/jc/fix-attr-docs-v1
Pull-Request: https://github.com/git/git/pull/1441

 attr.h | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)


base-commit: 904d404274fef6695c78a6b055edd184b72e2f9b

Comments

Junio C Hamano Jan. 22, 2023, 4:10 p.m. UTC | #1

"John Cai via GitGitGadget" <[e-mail]> writes:

> From: John Cai <[e-mail]>
>
> The instructions in attr.h describing what functions to call to check
> attributes is missing the index as the first argument to git_check_attr.
>
> Fix this to make it consistent with the actual function signature.

Sounds quite sensible.  It would have been very good to explain some
research in the above, like

    When 7a400a2c (attr: remove an implicit dependency on the_index,
    2018-08-13) started passing an index_state instance to
    git_check_attr(), it forgot to update the API documentation that
    was in Documentation/technical/api-gitattributes.txt.  Later,
    3a1b3415 (attr: move doc to attr.h, 2019-11-17) moved the API
    documentation to attr.h and made it to a comment, without
    realizing the earlier mistake.
    
or something like that.

Thanks.

> diff --git a/attr.h b/attr.h
> index 2f22dffadb3..47f1111f391 100644
> --- a/attr.h
> +++ b/attr.h
> @@ -45,7 +45,7 @@
>   * const char *path;
>   *
>   * setup_check();
> - * git_check_attr(path, check);
> + * git_check_attr(&the_index, path, check);
>   * ------------
>   *
>   * - Act on `.value` member of the result, left in `check->items[]`:
>
> base-commit: 904d404274fef6695c78a6b055edd184b72e2f9b

John Cai Jan. 23, 2023, 4:07 a.m. UTC | #2

Hi Junio,

On 22 Jan 2023, at 11:10, Junio C Hamano wrote:

> "John Cai via GitGitGadget" <[e-mail]> writes:
>
>> From: John Cai <[e-mail]>
>>
>> The instructions in attr.h describing what functions to call to check
>> attributes is missing the index as the first argument to git_check_attr.
>>
>> Fix this to make it consistent with the actual function signature.
>
> Sounds quite sensible.  It would have been very good to explain some
> research in the above, like
>
>     When 7a400a2c (attr: remove an implicit dependency on the_index,
>     2018-08-13) started passing an index_state instance to
>     git_check_attr(), it forgot to update the API documentation that
>     was in Documentation/technical/api-gitattributes.txt.  Later,
>     3a1b3415 (attr: move doc to attr.h, 2019-11-17) moved the API
>     documentation to attr.h and made it to a comment, without
>     realizing the earlier mistake.
>
> or something like that.

good tip about including some history. I'll include that in the re-roll

thanks!

>
> Thanks.
>
>> diff --git a/attr.h b/attr.h
>> index 2f22dffadb3..47f1111f391 100644
>> --- a/attr.h
>> +++ b/attr.h
>> @@ -45,7 +45,7 @@
>>   * const char *path;
>>   *
>>   * setup_check();
>> - * git_check_attr(path, check);
>> + * git_check_attr(&the_index, path, check);
>>   * ------------
>>   *
>>   * - Act on `.value` member of the result, left in `check->items[]`:
>>
>> base-commit: 904d404274fef6695c78a6b055edd184b72e2f9b

Patch

diff --git a/attr.h b/attr.h
index 2f22dffadb3..47f1111f391 100644
--- a/attr.h
+++ b/attr.h
@@ -45,7 +45,7 @@ 
  * const char *path;
  *
  * setup_check();
- * git_check_attr(path, check);
+ * git_check_attr(&the_index, path, check);
  * ------------
  *
  * - Act on `.value` member of the result, left in `check->items[]`: