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

From: Junio C Hamano <gitster@pobox.com>
Date: Sep 18, 2012, 17:21 UTC
Message-ID: <7va9wnnt5h.fsf@alter.siamese.dyndns.org>
In-Reply-To: <5058371C.8060209@alum.mit.edu>

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

> If another sort order is needed, then we will either have to audit
> existing string_list users to make sure that they don't rely on strcmp()
> ordering, or we will have to implement strcmp() ordering *plus* the new
> ordering.

What I was envisioning was to pass in an optional custom comparison when you instantiate a string_list object. Existing callers that rely on (or can live with, because they do not care about the exact order) the default order will continue to use the byte-value ordering, so there is no need for auditing. Only the new callers that want different ordering would set custom comparison routine.

But now I wrote it down, I realize that there is no _harm_ in documenting "we sort in byte-value order, so expect iterations on sorted string list to give them in that order to you" at all.

So let's go with your documentation patch as-is.

> It's not that I'm unwilling to implement 2; it's just that I still don't
> see any advantage to doing so before there is a demonstrated need for it.

As I said, I have this suspicion that the lack of demonstrated need is largely because the existing code that do _not_ use string-list don't do so because the interface is limited, so the argument is sort of self-fulfilling.