update documentation for pathPatterns

buildbot · Mar 14, 2013 · a80e97e · a80e97e
1 parent 55be8ae
commit a80e97e
Show file tree

Hide file tree

Showing 2 changed files with 19 additions and 11 deletions.
diff --git a/master/docs/developer/data.rst b/master/docs/developer/data.rst
@@ -290,19 +290,20 @@ See that module's description for details.
 
 .. py:class:: Endpoint
 
-    .. py:attribute:: pathPattern
-
-        :type: tuple
+    .. py:attribute:: pathPatterns
 
-        The path pattern which incoming paths must match to select this endpoint.
+        :type: string
 
-    .. py:attribute:: pathPatterns
+        This attribute defines the path patterns which incoming paths must match to select this endpoint.
+        Paths are specified as URIs, and can contain variables as parsed by :py:class:`buildbot.util.pathmatch.Matcher`.
+        Multiple paths are separated by whitespace.
 
-        :type: list of tuples
+        For example, the following specifies two paths with the second having a single variable::
 
-        List of path patterns which incoming paths must match to select this endpoint.
-        This is useful where the same endpoint class services multiple paths.
-        If specified, ``pathPattern`` is prepended to this list.
+            pathPatterns = """
+                /bugs
+                /component/i:component_name/bugs
+            """
 
     .. py:attribute:: rootLinkName
 

diff --git a/master/docs/developer/utils.rst b/master/docs/developer/utils.rst
@@ -538,15 +538,22 @@ buildbot.util.pathmatch
     This class implements the path-matching algorithm used by the data API.
 
     Patterns are tuples of strings, with strings beginning with a colon (``:``) denoting variables.
-    A tuple of strings matches a pattern if the lengths are identical, and if every non-variable pattern element matches exactly.
+    A character can precede the colon to indicate the variable type:
+
+        * ``i`` specifies an identifier (:ref:`identifier <type-identifier>`).
+        * ``n`` specifies a number (parseable by ``int``).
+
+    A tuple of strings matches a pattern if the lengths are identical, every variable matches and has the correct type, and every non-variable pattern element matches exactly.
 
     A matcher object takes patterns using dictionary-assignment syntax::
 
-        matcher[('change', ':changeid')] = Change()
+        ep = ChangeEndpoint()
+        matcher[('change', 'n:changeid')] = ep
 
     and performs matching using the dictionary-lookup syntax::
 
         changeEndpoint, kwargs = matcher[('change', '13')]
+        # -> (ep, {'changeid': 13})
 
     where the result is a tuple of the original assigned object (the ``Change`` instance in this case) and the values of any variables in the path.