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@xxxxxxxxxxxxxxx § 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@xxxxxxxx> Signed-off-by: Kristoffer Haugsbakk <code@xxxxxxxxxxxxxxx> ## Notes (series) ## - Suggested in: https://lore.kernel.org/git/20230601175218.GB4165405@xxxxxxxxxxxxxxxxxxxxxxx/ + v3: Suggested in: https://lore.kernel.org/git/20230601175218.GB4165405@xxxxxxxxxxxxxxxxxxxxxxx/ + 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
