Document the behaviour of _match_one_pattern in some detail

The possibilities are complicated enough that I didn't want to make
changes without having a complete description of what it actually
accepts/matches. Note that this text documents current behaviour, not
necessarily the behaviour we want. Some of this is undocumented and may
not be intended.

lib/ansible/inventory/__init__.py

@@ -228,9 +228,40 @@ class Inventory(object):
 
     def _match_one_pattern(self, pattern):
         """ 
-        Takes a single pattern (i.e., not "p1:p2") and returns a list of
-        matching host names. Does not take negatives or intersections
-        into account.
+        Takes a single pattern and returns a list of matching host names.
+        Ignores intersection (&) and exclusion (!) specifiers.
+
+        The pattern may be:
+
+            1. A regex starting with ~, e.g. '~[abc]*'
+            2. A shell glob pattern with ?/*/[chars]/[!chars], e.g. 'foo'
+            3. An ordinary word that matches itself only, e.g. 'foo'
+
+        The pattern is matched using the following rules:
+
+            1. If it's 'all', it matches all hosts in all groups.
+            2. Otherwise, for each known group name:
+                (a) if it matches the group name, the results include all hosts
+                    in the group or any of its children.
+                (b) otherwise, if it matches any hosts in the group, the results
+                    include the matching hosts.
+
+        This means that 'foo*' may match one or more groups (thus including all
+        hosts therein) but also hosts in other groups.
+
+        The built-in groups 'all' and 'ungrouped' are special. No pattern can
+        match these group names (though 'all' behaves as though it matches, as
+        described above). The word 'ungrouped' can match a host of that name,
+        and patterns like 'ungr*' and 'al*' can match either hosts or groups
+        other than all and ungrouped.
+
+        If the pattern matches one or more group names according to these rules,
+        it may have an optional range suffix to select a subset of the results.
+        This is allowed only if the pattern is not a regex, i.e. '~foo[1]' does
+        not work (the [1] is interpreted as part of the regex), but 'foo*[1]'
+        would work if 'foo*' matched the name of one or more groups.
+
+        Duplicate matches are always eliminated from the results.
         """
 
         if pattern.startswith("&") or pattern.startswith("!"):