mbox series

[v4,0/2] notes: update documentation for `use_default_notes`

Message ID cover.1685958731.git.code@khaugsbakk.name (mailing list archive)
Headers show
Series notes: update documentation for `use_default_notes` | expand

Message

Kristoffer Haugsbakk June 5, 2023, 10:05 a.m. UTC 
While I was working on [1] I found that the doc for the struct
`display_notes_opt` hadn’t been updated when one of the members were
renamed. I chose to post a separate patch/series.

[1] https://lore.kernel.org/git/cover.1685441207.git.code@khaugsbakk.name

§ Changes in v4 by patch

• 2: Document the struct members directly

Kristoffer Haugsbakk (2):
  notes: update documentation for `use_default_notes`
  notes: move the documentation to the struct

 notes.h | 19 +++++++++++--------
 1 file changed, 11 insertions(+), 8 deletions(-)

Range-diff against v3:
-:  ---------- > 1:  3eaa725d3a notes: update documentation for `use_default_notes`
1:  99c88c74ce ! 2:  ba147707ef notes: move the documentation to the struct
    @@ Metadata
      ## Commit message ##
         notes: move the documentation to the struct

    -    Its better to document the struct members on the struct definition
    -    instead of on a function that takes a pointer to such a struct. This
    -    will also make it easier to update the documentation in the future.
    +    Its better to document the struct members directly instead of on a
    +    function that takes a pointer to the struct. This will also make it
    +    easier to update the documentation in the future.
    +
    +    Make adjustments for this new context. Also drop “may contain” since we
    +    don’t need to emphasize that a list could be empty.

         Suggested-by: Jeff King <peff@peff.net>
         Signed-off-by: Kristoffer Haugsbakk <code@khaugsbakk.name>


      ## Notes (series) ##
    -    Suggested in: https://lore.kernel.org/git/20230601175218.GB4165405@coredump.intra.peff.net/
    +    v3: Suggested in: https://lore.kernel.org/git/20230601175218.GB4165405@coredump.intra.peff.net/
    +    v4:
    +        • Put docs on each member instead
    +        • Update commit message accordingly
    +        • Drop “may contain” since we don’t have to emphasize that a list
    +          could be empty
    +        • Formatting is based on clang-format and `bloom_filter_settings` in
    +          `bloom.h`

      ## notes.h ##
     @@ notes.h: void free_notes(struct notes_tree *t);
    -
      struct string_list;

    -+/*
    -+ * - use_default_notes: less than `0` is "unset", which means that the
    -+ *   default notes are shown iff no other notes are given. Otherwise,
    -+ *   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.
    -+ */
      struct display_notes_opt {
    ++	/*
    ++	 * Less than `0` is "unset", which means that the default notes
    ++	 * are shown iff no other notes are given. Otherwise,
    ++	 * treat it like a boolean.
    ++	 */
      	int use_default_notes;
    ++
    ++	/*
    ++	 * A list of globs (in the same style as notes.displayRef) where
    ++	 * notes should be loaded from.
    ++	 */
      	struct string_list extra_notes_refs;
    + };
    +
     @@ notes.h: void disable_display_notes(struct display_notes_opt *opt, int *show_notes);
      /*
       * Load the notes machinery for displaying several notes trees.
--
2.41.0

Comments

Jeff King June 6, 2023, 1:57 a.m. UTC | #1 
On Mon, Jun 05, 2023 at 12:05:21PM +0200, Kristoffer Haugsbakk wrote:

> While I was working on [1] I found that the doc for the struct
> `display_notes_opt` hadn’t been updated when one of the members were
> renamed. I chose to post a separate patch/series.
> 
> [1] https://lore.kernel.org/git/cover.1685441207.git.code@khaugsbakk.name
> 
> § Changes in v4 by patch
> 
> • 2: Document the struct members directly

Thanks, this version looks great to me!

-Peff