docs: elaborate on sortlist order

docs/ares_set_sortlist.3

@@ -20,7 +20,10 @@ sortlist.  The provided
 .IR sortstr
 string that holds a space separated list of IP-address-netmask pairs.  The
 netmask is optional but follows the address after a slash if present.  For example,
-"130.155.160.0/255.255.240.0 130.155.0.0".
+"130.155.160.0/255.255.240.0 130.155.0.0" will sort IPs in ascending
+order of appearance in the sortlist subnets, with those IPs that do
+not match any subnets coming last.  There is no particular order
+amongst IPs that tie in this sorting scheme.
 
 This function replaces any potentially previously configured address sortlist
 with the ones given in the configuration string.

src/lib/ares_gethostbyname.c

@@ -140,6 +140,11 @@ static void sort_addresses(const struct hostent  *host,
    * through the address list, with the loop invariant that everything
    * to the left of i1 is sorted.  In the loop body, the value at i1 is moved
    * back through the list (via i2) until it is in sorted order.
+   *
+   * The IPs are sorted in ascending order of corresponding sortlist
+   * indices, with those that don't match the subnets in the sortlist
+   * coming last.  There is no particular order amongst IPs that tie
+   * in this sorting scheme.
    */
   for (i1 = 0; host->h_addr_list[i1]; i1++) {
     memcpy(&a1, host->h_addr_list[i1], sizeof(struct in_addr));
@@ -196,6 +201,11 @@ static void sort6_addresses(const struct hostent  *host,
    * through the address list, with the loop invariant that everything
    * to the left of i1 is sorted.  In the loop body, the value at i1 is moved
    * back through the list (via i2) until it is in sorted order.
+   *
+   * The IPv6s are sorted in ascending order of corresponding sortlist
+   * indices, with those that don't match the subnets in the sortlist
+   * coming last.  There is no particular order amongst IPs that tie
+   * in this sorting scheme.
    */
   for (i1 = 0; host->h_addr_list[i1]; i1++) {
     memcpy(&a1, host->h_addr_list[i1], sizeof(struct ares_in6_addr));