Re: [PATCH] attr: fix instructions on how to check attrs

"John Cai via GitGitGadget" [off-list ref] writes:

From: John Cai <redacted>

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.

Hi Junio,

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

"John Cai via GitGitGadget" [off-list ref] writes:

quoted

From: John Cai <redacted>

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.

quoted

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