document th way extensions are sorted

git-svn-id: https://origsvn.digium.com/svn/asterisk/trunk@25613 65c4cc65-6c06-0410-ace0-fbb531ad65f3

pbx.c

@@ -3000,9 +3000,6 @@ static int show_dialplan_helper(int fd, char *context, char *exten, struct dialp
 		/* show this context? */
 		if (!context ||
 			!strcmp(ast_get_context_name(c), context)) {
-			dpc->context_existence = 1;
-
-			ast_lock_context(c);
 			/* XXX re-indent this block */
 				struct ast_exten *e;
 				struct ast_include *i;
@@ -3011,6 +3008,9 @@ static int show_dialplan_helper(int fd, char *context, char *exten, struct dialp
 				char buf[256], buf2[256];
 				int context_info_printed = 0;
 
+			dpc->context_existence = 1;
+			ast_lock_context(c);
+
 				/* are we looking for exten too? if yes, we print context
 				 * if we our extension only
 				 */
@@ -4105,7 +4105,27 @@ static void null_datad(void *foo)
 {
 }
 
-/*
+/*! \brief
+ * Main interface to add extensions to the list for out context.
+ *
+ * We sort extensions in order of matching preference, so that we can
+ * stop the search as soon as we find a suitable match.
+ * This ordering also takes care of wildcards such as '.' (meaning
+ * "one or more of any character") and '!' (which is 'earlymatch',
+ * meaning "zero or more of any character" but also impacts the
+ * return value from CANMATCH and EARLYMATCH.
+ * 
+ * The extension match rules defined in the devmeeting 2006.05.05 are
+ * quite simple: WE SELECT THE LONGEST MATCH.
+ * In detail, "longest" means the number of matched characters in
+ * the extension. In case of ties (e.g. _XXX and 333) in the length
+ * of a pattern, we give priority to entries with the smallest cardinality
+ * (e.g, [5-9] comes before [2-8] before the former has only 5 elements,
+ * while the latter has 7, etc.
+ * In case of same cardinality, the first element in the range counts.
+ * If we still have a tie, any final '!' will make this as a possibly
+ * less specific pattern.
+ *
  * EBUSY - can't lock
  * EEXIST - extension with the same priority exist and no replace is set
  *