docs/ure: Elaborate doc, update markup to the latest conventions.

docs/library/ure.rst

-:mod:`ure` -- regular expressions
-=================================
+:mod:`ure` -- simple regular expressions
+========================================
 
 .. module:: ure
    :synopsis: regular expressions
@@ -32,6 +32,10 @@ Supported operators are:
 
 ``'+?'``
 
+``'()'``
+   Grouping. Each group is capturing (a substring it captures can be accessed
+   with `match.group()` method).
+
 Counted repetitions (``{m,n}``), more advanced assertions, named groups,
 etc. are not supported.
 
@@ -39,18 +43,18 @@ etc. are not supported.
 Functions
 ---------
 
-.. function:: compile(regex)
+.. function:: compile(regex_str)
 
-   Compile regular expression, return ``regex`` object.
+   Compile regular expression, return `regex <regex>` object.
 
-.. function:: match(regex, string)
+.. function:: match(regex_str, string)
 
-   Match ``regex`` against ``string``. Match always happens from starting
-   position in a string.
+   Compile *regex_str* and match against *string*. Match always happens
+   from starting position in a string.
 
-.. function:: search(regex, string)
+.. function:: search(regex_str, string)
 
-   Search ``regex`` in a ``string``. Unlike ``match``, this will search
+   Compile *regex_str* and search it in a *string*. Unlike `match`, this will search
    string for first position which matches regex (which still may be
    0 if regex is anchored).
 
@@ -59,24 +63,33 @@ Functions
    Flag value, display debug information about compiled expression.
 
 
+.. _regex:
+
 Regex objects
 -------------
 
 Compiled regular expression. Instances of this class are created using
-``ure.compile()``.
+`ure.compile()`.
 
 .. method:: regex.match(string)
+            regex.search(string)
 
-.. method:: regex.search(string)
+   Similar to the module-level functions :meth:`match` and :meth:`search`.
+   Using methods is (much) more efficient if the same regex is applied to
+   multiple strings.
 
 .. method:: regex.split(string, max_split=-1)
 
+   Split a *string* using regex. If *max_split* is given, it specifies
+   maximum number of splits to perform. Returns list of strings (there
+   may be up to *max_split+1* elements if it's specified).
 
 Match objects
 -------------
 
-Match objects as returned by ``match()`` and ``search()`` methods.
+Match objects as returned by `match()` and `search()` methods.
 
 .. method:: match.group([index])
 
-   Only numeric groups are supported.
+   Return matching (sub)string. *index* is 0 for entire match,
+   1 and above for each capturing group. Only numeric groups are supported.