s4:dsdb:util_trusts: describe dns_cmp return values

Signed-off-by: Douglas Bagnall <douglas.bagnall@catalyst.net.nz>
Reviewed-by: Andrew Bartlett <abartlet@samba.org>

diff --git a/source4/dsdb/common/util_trusts.c b/source4/dsdb/common/util_trusts.c
index 5003e7499b01084b8ed0773bc16cb30b694d14c1..2d82d6918d5275ab885f8a083dc2eea7d33c1581 100644 (file)
--- a/source4/dsdb/common/util_trusts.c
+++ b/source4/dsdb/common/util_trusts.c
@@ -619,6 +619,22 @@ static NTSTATUS dsdb_trust_crossref_tdo_info(TALLOC_CTX *mem_ctx,
  *
  * The DNS names are compared per component, starting from
  * the last one.
+ *
+ * The function is usable in a sort, but the return value contains more
+ * information than a simple comparison. There are 5 return values, defined
+ * above.
+ *
+ * DNS_CMP_FIRST_IS_CHILD (-2) means the first argument is a sub-domain of the
+ * second. e.g. dns_cmp("foo.example.org", "example.org")
+ *
+ * DNS_CMP_FIRST_IS_LESS (-1) means the first argument sorts before the
+ * second, but is not a sub-domain. e.g. dns_cmp("eggsample.org", "example.org").
+ *
+ * DNS_CMP_SECOND_IS_CHILD (+2) and DNS_CMP_SECOND_IS_LESS (+1) have the
+ * similar expected meanings. DNS_CMP_MATCH (0) means equality.
+ *
+ * NULL values are the parent of all addresses, which means comparisons
+ * between a string and NULL will return +2 or -2.
  */
 static int dns_cmp(const char *s1, const char *s2)
 {