string-list: note in docs that callers can specify sorting function

Simple change to the string-list docs to reflect the fact that string-list now has a cmp member field these days that can be set to something other than strcmp().

Elijah Newren (1):
string-list: note in docs that callers can specify sorting function

 string-list.h | 6 ++++--
 1 file changed, 4 insertions(+), 2 deletions(-)

base-commit: 8679ef24ed64018bb62170c43ce73e0261c0600a
Published-As: https://github.com/gitgitgadget/git/releases/tag/pr-git-689%2Fnewren%2Fstring-list-update-docs-v1
Fetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-git-689/newren/string-list-update-docs-v1
Pull-Request: https://github.com/git/git/pull/689

gitgitgadget

From: Elijah Newren <[email protected]>

In commit 1959bf6430 (string_list API: document what "sorted" means, 2012-09-17), Documentation/technical/api-string-list.txt was updated to specify that strcmp() was used for sorting. In commit 8dd5afc926 (string-list: allow case-insensitive string list, 2013-01-07), a cmp member was added to struct string_list to allow callers to specify an alternative comparison function, but api-string-list.txt was not updated. In commit 4f665f2cf3 (string-list.h: move documentation from Documentation/api/ into header, 2017-09-26), the now out-dated api-string-list.txt documentation was moved into string-list.h. Update the docs to reflect the configurability of sorting.

---
 string-list.h | 6 ++++--
 1 file changed, 4 insertions(+), 2 deletions(-)

index 7bb0ad07e6..6c5d274126 100644
@@ -4,7 +4,8 @@
 /**
  * The string_list API offers a data structure and functions to handle
  * sorted and unsorted arrays of strings.  A "sorted" list is one whose
- * entries are sorted by string value in `strcmp()` order.
+ * entries are sorted by string value in the order specified by the `cmp`
+ * member (`strcmp()` by default).
  *
  * The caller:
  *

@@ -209,7 +210,8 @@ struct string_list_item *string_list_append(struct string_list *list, const char
 struct string_list_item *string_list_append_nodup(struct string_list *list, char *string);
 
 /**
- * Sort the list's entries by string value in `strcmp()` order.
+ * Sort the list's entries by string value in order specified by list->cmp
+ * (strcmp() if list->cmp is NULL).
  */
 void string_list_sort(struct string_list *list);
 

gitgitgadget