Re: [PATCH] string_list API: document what "sorted" means.

[Junio C Hamano <gitster@pobox.com>]

Michael Haggerty <mhagger@alum.mit.edu> writes:

> Junio pointed out that the sort order currently used by string_list
> could be considered to be an implementation detail internal to
> string_list.  But the sort order is already visible to the outside
> world (e.g., via iteration or via print_string_list()), so it
> shouldn't be changed willy-nilly.  Therefore, document the current
> sort order as part of the API's contract.
>
> (If, at some future time, somebody wants a string_list that is sorted
> by a different criterion, then the order should be made specifiable
> via a callback function specified by the user.)

As I said in a separate message, we do not give any documented
guarantee on the order the strings comes out of print_string_list(),
other than "if you are using the unsorted list function to insert or
append strings, we won't muck with the order of the items and you
will get your strings back in the order you gave us".  Until we add
a callback that the user can specify at the time of string list
initialization, I do not think it is wise to cast it in stone and
declare it as "shouldn't be changed willy-nilly", unnecessarily
painting us into a corner that we need to expend extra effort to get
out of.

Besides, nobody calls print_string_list() in the first place. I have
always considered it as a debugging aid.