{"thread":{"id":"59812","subject":"[PATCH] notes: update documentation for `use_default_notes`","startedAt":"2023-05-31T09:52:49Z","lastAt":"2023-06-06T01:57:49Z","messageCount":13,"participants":["Kristoffer Haugsbakk","Jeff King"],"isPatch":true,"patchVersion":1,"patchTotal":null},"messages":[{"id":"477827","messageId":"b3829cb0d1e36a5ebb44a315fe32037f2a3f6c7a.1685526558.git.code@khaugsbakk.name","threadId":"59812","inReplyTo":null,"subject":"[PATCH] notes: update documentation for `use_default_notes`","fromName":"Kristoffer Haugsbakk","fromEmail":"code@khaugsbakk.name","sentAt":"2023-05-31T09:52:07Z","receivedAt":"2023-05-31T09:52:49Z","isPatch":true,"sender":{"key":"code@khaugsbakk.name","avatar":"https://avatars.githubusercontent.com/u/2229597?v=4"},"body":"`suppress_default_notes` was renamed to `use_default_notes` in\n3a03cf6b1d (notes: refactor display notes default handling,\n2011-03-29).\n\nThe commit message says that “values less than one [indicates] “not\nset” ”, but I think what was meant was “less than zero”.\n\nSigned-off-by: Kristoffer Haugsbakk <code@khaugsbakk.name>\n---\n\nNotes (series):\n    See also: https://lore.kernel.org/git/cover.1685441207.git.code@khaugsbakk.name\n    \n    Found while working on that. But this change could be posted\n    separately.\n\n notes.h | 5 +++--\n 1 file changed, 3 insertions(+), 2 deletions(-)\n\ndiff --git a/notes.h b/notes.h\nindex c1682c39a9..69b6120146 100644\n--- a/notes.h\n+++ b/notes.h\n@@ -286,8 +286,9 @@ void disable_display_notes(struct display_notes_opt *opt, int *show_notes);\n  * If 'opt' is not NULL, then it specifies additional settings for the\n  * displaying:\n  *\n- * - suppress_default_notes indicates that the notes from\n- *   core.notesRef and notes.displayRef should not be loaded.\n+ * - use_default_notes: less than `0` is \"unset\", which means that the\n+ *   deafult refs are show iff no other notes are given. Else treat like\n+ *   a boolean.\n  *\n  * - extra_notes_refs may contain a list of globs (in the same style\n  *   as notes.displayRef) where notes should be loaded from.\n-- \n2.41.0.rc2\n\n"},{"id":"477830","messageId":"3c757bcb3d5c8b597b7f267549f90e1a021d229a.1685535115.git.code@khaugsbakk.name","threadId":"59812","inReplyTo":"b3829cb0d1e36a5ebb44a315fe32037f2a3f6c7a.1685526558.git.code@khaugsbakk.name","subject":"[PATCH v2] notes: update documentation for `use_default_notes`","fromName":"Kristoffer Haugsbakk","fromEmail":"code@khaugsbakk.name","sentAt":"2023-05-31T12:14:21Z","receivedAt":"2023-05-31T12:15:45Z","isPatch":true,"sender":{"key":"code@khaugsbakk.name","avatar":"https://avatars.githubusercontent.com/u/2229597?v=4"},"body":"`suppress_default_notes` was renamed to `use_default_notes` in\n3a03cf6b1d (notes: refactor display notes default handling,\n2011-03-29).\n\nThe commit message says that “values less than one [indicates] “not\nset” ”, but I think what was meant was “less than zero”.\n\nSigned-off-by: Kristoffer Haugsbakk <code@khaugsbakk.name>\n---\n\nNotes (series):\n    § v2\n    \n    • Fix sloppy typos (sorry about that)\n    • “default notes” instead of “default refs”\n    • Don’t drop “it” (“treat it like”)\n\n notes.h | 5 +++--\n 1 file changed, 3 insertions(+), 2 deletions(-)\n\ndiff --git a/notes.h b/notes.h\nindex c1682c39a9..826a2595fa 100644\n--- a/notes.h\n+++ b/notes.h\n@@ -286,8 +286,9 @@ void disable_display_notes(struct display_notes_opt *opt, int *show_notes);\n  * If 'opt' is not NULL, then it specifies additional settings for the\n  * displaying:\n  *\n- * - suppress_default_notes indicates that the notes from\n- *   core.notesRef and notes.displayRef should not be loaded.\n+ * - use_default_notes: less than `0` is \"unset\", which means that the\n+ *   default notes are shown iff no other notes are given. Else treat it\n+ *   like a boolean.\n  *\n  * - extra_notes_refs may contain a list of globs (in the same style\n  *   as notes.displayRef) where notes should be loaded from.\n-- \n2.41.0.rc2\n\n"},{"id":"477892","messageId":"20230601175218.GB4165405@coredump.intra.peff.net","threadId":"59812","inReplyTo":"3c757bcb3d5c8b597b7f267549f90e1a021d229a.1685535115.git.code@khaugsbakk.name","subject":"Re: [PATCH v2] notes: update documentation for `use_default_notes`","fromName":"Jeff King","fromEmail":"peff@peff.net","sentAt":"2023-06-01T17:52:18Z","receivedAt":"2023-06-01T17:52:23Z","isPatch":true,"sender":{"key":"peff@peff.net","avatar":"https://avatars.githubusercontent.com/u/45925?v=4"},"body":"On Wed, May 31, 2023 at 02:14:21PM +0200, Kristoffer Haugsbakk wrote:\n\n> `suppress_default_notes` was renamed to `use_default_notes` in\n> 3a03cf6b1d (notes: refactor display notes default handling,\n> 2011-03-29).\n> \n> The commit message says that “values less than one [indicates] “not\n> set” ”, but I think what was meant was “less than zero”.\n\nYes, I think you're right. Thanks for catching my error, however\nbelatedly. ;)\n\n> diff --git a/notes.h b/notes.h\n> index c1682c39a9..826a2595fa 100644\n> --- a/notes.h\n> +++ b/notes.h\n> @@ -286,8 +286,9 @@ void disable_display_notes(struct display_notes_opt *opt, int *show_notes);\n>   * If 'opt' is not NULL, then it specifies additional settings for the\n>   * displaying:\n>   *\n> - * - suppress_default_notes indicates that the notes from\n> - *   core.notesRef and notes.displayRef should not be loaded.\n> + * - use_default_notes: less than `0` is \"unset\", which means that the\n> + *   default notes are shown iff no other notes are given. Else treat it\n> + *   like a boolean.\n>   *\n>   * - extra_notes_refs may contain a list of globs (in the same style\n>   *   as notes.displayRef) where notes should be loaded from.\n\nThis looks good to me. Arguably these should be documented in the\ndefinition of \"struct display_notes_opt\", which would have avoided the\nproblem (3a03cf6b1d would not have forgotten to update the name since it\nwould be right there already). But it may not be worth the trouble to\nmove them now.\n\n-Peff\n"},{"id":"477928","messageId":"6b7ead0c-97e5-430a-8034-ad870c9b2699@app.fastmail.com","threadId":"59812","inReplyTo":"20230601175218.GB4165405@coredump.intra.peff.net","subject":"Re: [PATCH v2] notes: update documentation for `use_default_notes`","fromName":"Kristoffer Haugsbakk","fromEmail":"code@khaugsbakk.name","sentAt":"2023-06-02T10:09:11Z","receivedAt":"2023-06-02T10:10:12Z","isPatch":true,"sender":{"key":"code@khaugsbakk.name","avatar":"https://avatars.githubusercontent.com/u/2229597?v=4"},"body":"Hi Peff\n\nOn Thu, Jun 1, 2023, at 19:52, Jeff King wrote:\n> This looks good to me. Arguably these should be documented in the\n> definition of \"struct display_notes_opt\", which would have avoided the\n> problem (3a03cf6b1d would not have forgotten to update the name since it\n> would be right there already). But it may not be worth the trouble to\n> move them now.\n\nSounds like a good change to me. I’ll make a new version tomorrow unless\nsomeone disagrees about that before that time.\n\n-- \nKristoffer Haugsbakk\n"},{"id":"478029","messageId":"cover.1685904424.git.code@khaugsbakk.name","threadId":"59812","inReplyTo":"b3829cb0d1e36a5ebb44a315fe32037f2a3f6c7a.1685526558.git.code@khaugsbakk.name","subject":"[PATCH v3 0/2] notes: update documentation for `use_default_notes`","fromName":"Kristoffer Haugsbakk","fromEmail":"code@khaugsbakk.name","sentAt":"2023-06-04T18:53:58Z","receivedAt":"2023-06-04T18:54:46Z","isPatch":true,"sender":{"key":"code@khaugsbakk.name","avatar":"https://avatars.githubusercontent.com/u/2229597?v=4"},"body":"While I was working on [1] I found that the doc for the struct\n`display_notes_opt` hadn’t been updated when one of the members were\nrenamed. I chose to post a separate patch/series.\n\n[1] https://lore.kernel.org/git/cover.1685441207.git.code@khaugsbakk.name\n\n§ Changes in v3 by patch\n\n• 1: change initial “else” to “otherwise”\n• 1. tweak commit message\n• 2: New: move documentation to struct definition\n\nKristoffer Haugsbakk (2):\n  notes: update documentation for `use_default_notes`\n  notes: move the documentation to the struct\n\n notes.h | 17 +++++++++--------\n 1 file changed, 9 insertions(+), 8 deletions(-)\n\nRange-diff against v2:\n1:  3c757bcb3d ! 1:  3eaa725d3a notes: update documentation for `use_default_notes`\n    @@ Commit message\n         2011-03-29).\n\n         The commit message says that “values less than one [indicates] “not\n    -    set” ”, but I think what was meant was “less than zero”.\n    +    set” ”, but what was meant was probably “less than zero” (the author of\n    +    3a03cf6b1d agrees on this point).\n\n         Signed-off-by: Kristoffer Haugsbakk <code@khaugsbakk.name>\n\n    -\n    - ## Notes (series) ##\n    -    § v2\n    -\n    -    • Fix sloppy typos (sorry about that)\n    -    • “default notes” instead of “default refs”\n    -    • Don’t drop “it” (“treat it like”)\n    -\n      ## notes.h ##\n     @@ notes.h: void disable_display_notes(struct display_notes_opt *opt, int *show_notes);\n       * If 'opt' is not NULL, then it specifies additional settings for the\n    @@ notes.h: void disable_display_notes(struct display_notes_opt *opt, int *show_not\n     - * - suppress_default_notes indicates that the notes from\n     - *   core.notesRef and notes.displayRef should not be loaded.\n     + * - use_default_notes: less than `0` is \"unset\", which means that the\n    -+ *   default notes are shown iff no other notes are given. Else treat it\n    -+ *   like a boolean.\n    ++ *   default notes are shown iff no other notes are given. Otherwise,\n    ++ *   treat it like a boolean.\n       *\n       * - extra_notes_refs may contain a list of globs (in the same style\n       *   as notes.displayRef) where notes should be loaded from.\n-:  ---------- > 2:  99c88c74ce notes: move the documentation to the struct\n--\n2.41.0\n"},{"id":"478030","messageId":"99c88c74ceab751c0540b51d98bf339bffc098ef.1685904424.git.code@khaugsbakk.name","threadId":"59812","inReplyTo":"cover.1685904424.git.code@khaugsbakk.name","subject":"[PATCH v3 2/2] notes: move the documentation to the struct","fromName":"Kristoffer Haugsbakk","fromEmail":"code@khaugsbakk.name","sentAt":"2023-06-04T18:54:00Z","receivedAt":"2023-06-04T18:55:07Z","isPatch":true,"sender":{"key":"code@khaugsbakk.name","avatar":"https://avatars.githubusercontent.com/u/2229597?v=4"},"body":"Its better to document the struct members on the struct definition\ninstead of on a function that takes a pointer to such a struct. This\nwill also make it easier to update the documentation in the future.\n\nSuggested-by: Jeff King <peff@peff.net>\nSigned-off-by: Kristoffer Haugsbakk <code@khaugsbakk.name>\n---\n\nNotes (series):\n    Suggested in: https://lore.kernel.org/git/20230601175218.GB4165405@coredump.intra.peff.net/\n\n notes.h | 18 +++++++++---------\n 1 file changed, 9 insertions(+), 9 deletions(-)\n\ndiff --git a/notes.h b/notes.h\nindex a823840e49..c63b275d7a 100644\n--- a/notes.h\n+++ b/notes.h\n@@ -255,6 +255,14 @@ void free_notes(struct notes_tree *t);\n \n struct string_list;\n \n+/*\n+ * - use_default_notes: less than `0` is \"unset\", which means that the\n+ *   default notes are shown iff no other notes are given. Otherwise,\n+ *   treat it like a boolean.\n+ *\n+ * - extra_notes_refs may contain a list of globs (in the same style\n+ *   as notes.displayRef) where notes should be loaded from.\n+ */\n struct display_notes_opt {\n \tint use_default_notes;\n \tstruct string_list extra_notes_refs;\n@@ -283,15 +291,7 @@ void disable_display_notes(struct display_notes_opt *opt, int *show_notes);\n /*\n  * Load the notes machinery for displaying several notes trees.\n  *\n- * If 'opt' is not NULL, then it specifies additional settings for the\n- * displaying:\n- *\n- * - use_default_notes: less than `0` is \"unset\", which means that the\n- *   default notes are shown iff no other notes are given. Otherwise,\n- *   treat it like a boolean.\n- *\n- * - extra_notes_refs may contain a list of globs (in the same style\n- *   as notes.displayRef) where notes should be loaded from.\n+ * 'opt' may be NULL.\n  */\n void load_display_notes(struct display_notes_opt *opt);\n \n-- \n2.41.0\n\n"},{"id":"478031","messageId":"3eaa725d3a476e3cfd7331104f35bbd322d9394f.1685904424.git.code@khaugsbakk.name","threadId":"59812","inReplyTo":"cover.1685904424.git.code@khaugsbakk.name","subject":"[PATCH v3 1/2] notes: update documentation for `use_default_notes`","fromName":"Kristoffer Haugsbakk","fromEmail":"code@khaugsbakk.name","sentAt":"2023-06-04T18:53:59Z","receivedAt":"2023-06-04T18:55:07Z","isPatch":true,"sender":{"key":"code@khaugsbakk.name","avatar":"https://avatars.githubusercontent.com/u/2229597?v=4"},"body":"`suppress_default_notes` was renamed to `use_default_notes` in\n3a03cf6b1d (notes: refactor display notes default handling,\n2011-03-29).\n\nThe commit message says that “values less than one [indicates] “not\nset” ”, but what was meant was probably “less than zero” (the author of\n3a03cf6b1d agrees on this point).\n\nSigned-off-by: Kristoffer Haugsbakk <code@khaugsbakk.name>\n---\n notes.h | 5 +++--\n 1 file changed, 3 insertions(+), 2 deletions(-)\n\ndiff --git a/notes.h b/notes.h\nindex c1682c39a9..a823840e49 100644\n--- a/notes.h\n+++ b/notes.h\n@@ -286,8 +286,9 @@ void disable_display_notes(struct display_notes_opt *opt, int *show_notes);\n  * If 'opt' is not NULL, then it specifies additional settings for the\n  * displaying:\n  *\n- * - suppress_default_notes indicates that the notes from\n- *   core.notesRef and notes.displayRef should not be loaded.\n+ * - use_default_notes: less than `0` is \"unset\", which means that the\n+ *   default notes are shown iff no other notes are given. Otherwise,\n+ *   treat it like a boolean.\n  *\n  * - extra_notes_refs may contain a list of globs (in the same style\n  *   as notes.displayRef) where notes should be loaded from.\n-- \n2.41.0\n\n"},{"id":"478037","messageId":"20230605045042.GA66000@coredump.intra.peff.net","threadId":"59812","inReplyTo":"99c88c74ceab751c0540b51d98bf339bffc098ef.1685904424.git.code@khaugsbakk.name","subject":"Re: [PATCH v3 2/2] notes: move the documentation to the struct","fromName":"Jeff King","fromEmail":"peff@peff.net","sentAt":"2023-06-05T04:50:42Z","receivedAt":"2023-06-05T04:50:52Z","isPatch":true,"sender":{"key":"peff@peff.net","avatar":"https://avatars.githubusercontent.com/u/45925?v=4"},"body":"On Sun, Jun 04, 2023 at 08:54:00PM +0200, Kristoffer Haugsbakk wrote:\n\n> Its better to document the struct members on the struct definition\n> instead of on a function that takes a pointer to such a struct. This\n> will also make it easier to update the documentation in the future.\n\nThis is better, I think, but...\n\n> +/*\n> + * - use_default_notes: less than `0` is \"unset\", which means that the\n> + *   default notes are shown iff no other notes are given. Otherwise,\n> + *   treat it like a boolean.\n> + *\n> + * - extra_notes_refs may contain a list of globs (in the same style\n> + *   as notes.displayRef) where notes should be loaded from.\n> + */\n>  struct display_notes_opt {\n>  \tint use_default_notes;\n>  \tstruct string_list extra_notes_refs;\n\n...what I had meant to suggest was putting the documentation next to\neach field, like:\n\n  struct foo {\n\t/* when set, enable \"bar\" for all frotz's */\n\tint use_bar;\n\n\t/* etc... */\n  };\n\nFor an example, try \"struct bloom_filter_settings\" in bloom.h (though\nthere are many others, too).\n\n-Peff\n\n\n\n\n> @@ -283,15 +291,7 @@ void disable_display_notes(struct display_notes_opt *opt, int *show_notes);\n>  /*\n>   * Load the notes machinery for displaying several notes trees.\n>   *\n> - * If 'opt' is not NULL, then it specifies additional settings for the\n> - * displaying:\n> - *\n> - * - use_default_notes: less than `0` is \"unset\", which means that the\n> - *   default notes are shown iff no other notes are given. Otherwise,\n> - *   treat it like a boolean.\n> - *\n> - * - extra_notes_refs may contain a list of globs (in the same style\n> - *   as notes.displayRef) where notes should be loaded from.\n> + * 'opt' may be NULL.\n>   */\n>  void load_display_notes(struct display_notes_opt *opt);\n>  \n> -- \n> 2.41.0\n> \n"},{"id":"478040","messageId":"cover.1685958731.git.code@khaugsbakk.name","threadId":"59812","inReplyTo":"b3829cb0d1e36a5ebb44a315fe32037f2a3f6c7a.1685526558.git.code@khaugsbakk.name","subject":"[PATCH v4 0/2] notes: update documentation for `use_default_notes`","fromName":"Kristoffer Haugsbakk","fromEmail":"code@khaugsbakk.name","sentAt":"2023-06-05T10:05:21Z","receivedAt":"2023-06-05T10:06:25Z","isPatch":true,"sender":{"key":"code@khaugsbakk.name","avatar":"https://avatars.githubusercontent.com/u/2229597?v=4"},"body":"While I was working on [1] I found that the doc for the struct\n`display_notes_opt` hadn’t been updated when one of the members were\nrenamed. I chose to post a separate patch/series.\n\n[1] https://lore.kernel.org/git/cover.1685441207.git.code@khaugsbakk.name\n\n§ Changes in v4 by patch\n\n• 2: Document the struct members directly\n\nKristoffer Haugsbakk (2):\n  notes: update documentation for `use_default_notes`\n  notes: move the documentation to the struct\n\n notes.h | 19 +++++++++++--------\n 1 file changed, 11 insertions(+), 8 deletions(-)\n\nRange-diff against v3:\n-:  ---------- > 1:  3eaa725d3a notes: update documentation for `use_default_notes`\n1:  99c88c74ce ! 2:  ba147707ef notes: move the documentation to the struct\n    @@ Metadata\n      ## Commit message ##\n         notes: move the documentation to the struct\n\n    -    Its better to document the struct members on the struct definition\n    -    instead of on a function that takes a pointer to such a struct. This\n    -    will also make it easier to update the documentation in the future.\n    +    Its better to document the struct members directly instead of on a\n    +    function that takes a pointer to the struct. This will also make it\n    +    easier to update the documentation in the future.\n    +\n    +    Make adjustments for this new context. Also drop “may contain” since we\n    +    don’t need to emphasize that a list could be empty.\n\n         Suggested-by: Jeff King <peff@peff.net>\n         Signed-off-by: Kristoffer Haugsbakk <code@khaugsbakk.name>\n\n\n      ## Notes (series) ##\n    -    Suggested in: https://lore.kernel.org/git/20230601175218.GB4165405@coredump.intra.peff.net/\n    +    v3: Suggested in: https://lore.kernel.org/git/20230601175218.GB4165405@coredump.intra.peff.net/\n    +    v4:\n    +        • Put docs on each member instead\n    +        • Update commit message accordingly\n    +        • Drop “may contain” since we don’t have to emphasize that a list\n    +          could be empty\n    +        • Formatting is based on clang-format and `bloom_filter_settings` in\n    +          `bloom.h`\n\n      ## notes.h ##\n     @@ notes.h: void free_notes(struct notes_tree *t);\n    -\n      struct string_list;\n\n    -+/*\n    -+ * - use_default_notes: less than `0` is \"unset\", which means that the\n    -+ *   default notes are shown iff no other notes are given. Otherwise,\n    -+ *   treat it like a boolean.\n    -+ *\n    -+ * - extra_notes_refs may contain a list of globs (in the same style\n    -+ *   as notes.displayRef) where notes should be loaded from.\n    -+ */\n      struct display_notes_opt {\n    ++\t/*\n    ++\t * Less than `0` is \"unset\", which means that the default notes\n    ++\t * are shown iff no other notes are given. Otherwise,\n    ++\t * treat it like a boolean.\n    ++\t */\n      \tint use_default_notes;\n    ++\n    ++\t/*\n    ++\t * A list of globs (in the same style as notes.displayRef) where\n    ++\t * notes should be loaded from.\n    ++\t */\n      \tstruct string_list extra_notes_refs;\n    + };\n    +\n     @@ notes.h: void disable_display_notes(struct display_notes_opt *opt, int *show_notes);\n      /*\n       * Load the notes machinery for displaying several notes trees.\n--\n2.41.0\n"},{"id":"478041","messageId":"3eaa725d3a476e3cfd7331104f35bbd322d9394f.1685958731.git.code@khaugsbakk.name","threadId":"59812","inReplyTo":"cover.1685958731.git.code@khaugsbakk.name","subject":"[PATCH v4 1/2] notes: update documentation for `use_default_notes`","fromName":"Kristoffer Haugsbakk","fromEmail":"code@khaugsbakk.name","sentAt":"2023-06-05T10:05:22Z","receivedAt":"2023-06-05T10:06:30Z","isPatch":true,"sender":{"key":"code@khaugsbakk.name","avatar":"https://avatars.githubusercontent.com/u/2229597?v=4"},"body":"`suppress_default_notes` was renamed to `use_default_notes` in\n3a03cf6b1d (notes: refactor display notes default handling,\n2011-03-29).\n\nThe commit message says that “values less than one [indicates] “not\nset” ”, but what was meant was probably “less than zero” (the author of\n3a03cf6b1d agrees on this point).\n\nSigned-off-by: Kristoffer Haugsbakk <code@khaugsbakk.name>\n---\n notes.h | 5 +++--\n 1 file changed, 3 insertions(+), 2 deletions(-)\n\ndiff --git a/notes.h b/notes.h\nindex c1682c39a9..a823840e49 100644\n--- a/notes.h\n+++ b/notes.h\n@@ -286,8 +286,9 @@ void disable_display_notes(struct display_notes_opt *opt, int *show_notes);\n  * If 'opt' is not NULL, then it specifies additional settings for the\n  * displaying:\n  *\n- * - suppress_default_notes indicates that the notes from\n- *   core.notesRef and notes.displayRef should not be loaded.\n+ * - use_default_notes: less than `0` is \"unset\", which means that the\n+ *   default notes are shown iff no other notes are given. Otherwise,\n+ *   treat it like a boolean.\n  *\n  * - extra_notes_refs may contain a list of globs (in the same style\n  *   as notes.displayRef) where notes should be loaded from.\n-- \n2.41.0\n\n"},{"id":"478042","messageId":"ba147707efe382e64a6559e05b8f266c436bdfa0.1685958731.git.code@khaugsbakk.name","threadId":"59812","inReplyTo":"cover.1685958731.git.code@khaugsbakk.name","subject":"[PATCH v4 2/2] notes: move the documentation to the struct","fromName":"Kristoffer Haugsbakk","fromEmail":"code@khaugsbakk.name","sentAt":"2023-06-05T10:05:23Z","receivedAt":"2023-06-05T10:06:38Z","isPatch":true,"sender":{"key":"code@khaugsbakk.name","avatar":"https://avatars.githubusercontent.com/u/2229597?v=4"},"body":"Its better to document the struct members directly instead of on a\nfunction that takes a pointer to the struct. This will also make it\neasier to update the documentation in the future.\n\nMake adjustments for this new context. Also drop “may contain” since we\ndon’t need to emphasize that a list could be empty.\n\nSuggested-by: Jeff King <peff@peff.net>\nSigned-off-by: Kristoffer Haugsbakk <code@khaugsbakk.name>\n---\n\nNotes (series):\n    v3: Suggested in: https://lore.kernel.org/git/20230601175218.GB4165405@coredump.intra.peff.net/\n    v4:\n        • Put docs on each member instead\n        • Update commit message accordingly\n        • Drop “may contain” since we don’t have to emphasize that a list\n          could be empty\n        • Formatting is based on clang-format and `bloom_filter_settings` in\n          `bloom.h`\n\n notes.h | 20 +++++++++++---------\n 1 file changed, 11 insertions(+), 9 deletions(-)\n\ndiff --git a/notes.h b/notes.h\nindex a823840e49..064fd7143a 100644\n--- a/notes.h\n+++ b/notes.h\n@@ -256,7 +256,17 @@ void free_notes(struct notes_tree *t);\n struct string_list;\n \n struct display_notes_opt {\n+\t/*\n+\t * Less than `0` is \"unset\", which means that the default notes\n+\t * are shown iff no other notes are given. Otherwise,\n+\t * treat it like a boolean.\n+\t */\n \tint use_default_notes;\n+\n+\t/*\n+\t * A list of globs (in the same style as notes.displayRef) where\n+\t * notes should be loaded from.\n+\t */\n \tstruct string_list extra_notes_refs;\n };\n \n@@ -283,15 +293,7 @@ void disable_display_notes(struct display_notes_opt *opt, int *show_notes);\n /*\n  * Load the notes machinery for displaying several notes trees.\n  *\n- * If 'opt' is not NULL, then it specifies additional settings for the\n- * displaying:\n- *\n- * - use_default_notes: less than `0` is \"unset\", which means that the\n- *   default notes are shown iff no other notes are given. Otherwise,\n- *   treat it like a boolean.\n- *\n- * - extra_notes_refs may contain a list of globs (in the same style\n- *   as notes.displayRef) where notes should be loaded from.\n+ * 'opt' may be NULL.\n  */\n void load_display_notes(struct display_notes_opt *opt);\n \n-- \n2.41.0\n\n"},{"id":"478043","messageId":"35a072c1-c9b5-4aa0-b798-4e86f14571ca@app.fastmail.com","threadId":"59812","inReplyTo":"20230605045042.GA66000@coredump.intra.peff.net","subject":"Re: [PATCH v3 2/2] notes: move the documentation to the struct","fromName":"Kristoffer Haugsbakk","fromEmail":"code@khaugsbakk.name","sentAt":"2023-06-05T10:07:42Z","receivedAt":"2023-06-05T10:08:06Z","isPatch":true,"sender":{"key":"code@khaugsbakk.name","avatar":"https://avatars.githubusercontent.com/u/2229597?v=4"},"body":"On Mon, Jun 5, 2023, at 06:50, Jeff King wrote:\n> This is better, I think, but...\n>\n> [snip]\n>\n> ...what I had meant to suggest was putting the documentation next to\n> each field, like:\n\nThat make even more sense. :)\n\n-- \nKristoffer Haugsbakk\n"},{"id":"478061","messageId":"20230606015739.GB89456@coredump.intra.peff.net","threadId":"59812","inReplyTo":"cover.1685958731.git.code@khaugsbakk.name","subject":"Re: [PATCH v4 0/2] notes: update documentation for `use_default_notes`","fromName":"Jeff King","fromEmail":"peff@peff.net","sentAt":"2023-06-06T01:57:39Z","receivedAt":"2023-06-06T01:57:49Z","isPatch":true,"sender":{"key":"peff@peff.net","avatar":"https://avatars.githubusercontent.com/u/45925?v=4"},"body":"On Mon, Jun 05, 2023 at 12:05:21PM +0200, Kristoffer Haugsbakk wrote:\n\n> While I was working on [1] I found that the doc for the struct\n> `display_notes_opt` hadn’t been updated when one of the members were\n> renamed. I chose to post a separate patch/series.\n> \n> [1] https://lore.kernel.org/git/cover.1685441207.git.code@khaugsbakk.name\n> \n> § Changes in v4 by patch\n> \n> • 2: Document the struct members directly\n\nThanks, this version looks great to me!\n\n-Peff\n"}]}