Re: [PATCH v2] notes: update documentation for `use_default_notes`

[Jeff King <peff@peff.net>]

On Wed, May 31, 2023 at 02:14:21PM +0200, Kristoffer Haugsbakk wrote:

> `suppress_default_notes` was renamed to `use_default_notes` in
> 3a03cf6b1d (notes: refactor display notes default handling,
> 2011-03-29).
> 
> The commit message says that “values less than one [indicates] “not
> set” ”, but I think what was meant was “less than zero”.

Yes, I think you're right. Thanks for catching my error, however
belatedly. ;)

> diff --git a/notes.h b/notes.h
> index c1682c39a9..826a2595fa 100644
> --- a/notes.h
> +++ b/notes.h
> @@ -286,8 +286,9 @@ void disable_display_notes(struct display_notes_opt *opt, int *show_notes);
>   * If 'opt' is not NULL, then it specifies additional settings for the
>   * displaying:
>   *
> - * - suppress_default_notes indicates that the notes from
> - *   core.notesRef and notes.displayRef should not be loaded.
> + * - use_default_notes: less than `0` is "unset", which means that the
> + *   default notes are shown iff no other notes are given. Else treat it
> + *   like a boolean.
>   *
>   * - extra_notes_refs may contain a list of globs (in the same style
>   *   as notes.displayRef) where notes should be loaded from.

This looks good to me. Arguably these should be documented in the
definition of "struct display_notes_opt", which would have avoided the
problem (3a03cf6b1d would not have forgotten to update the name since it
would be right there already). But it may not be worth the trouble to
move them now.

-Peff