[doc] Update tools' doc and add some doctests

Change-Id: Iaaa01bf5635bb219fe49237e0afbdeb6f76e9aa9
---
M pywikibot/tools/__init__.py
1 file changed, 34 insertions(+), 6 deletions(-)

diff --git a/pywikibot/tools/__init__.py b/pywikibot/tools/__init__.py
index bad616f..902653e 100644
--- a/pywikibot/tools/__init__.py
+++ b/pywikibot/tools/__init__.py
@@ -264,6 +264,11 @@
 
     Empty strings are supported. The original string is not changed.
 
+    **Example**:
+
+    >>> first_lower('Hello World')
+    'hello World'
+
     .. versionadded:: 3.0
     """
     return string[:1].lower() + string[1:]
@@ -275,13 +280,16 @@
 
     Empty strings are supported. The original string is not changed.
 
-    .. versionadded:: 3.0
+    **Example**:
 
-    .. note:: MediaWiki doesn't capitalize
-       some characters the same way as Python.
-       This function tries to be close to
-       MediaWiki's capitalize function in
-       title.php. See T179115 and T200357.
+    >>> first_upper('hello World')
+    'Hello World'
+
+    .. versionadded:: 3.0
+    .. note:: MediaWiki doesn't capitalize some characters the same way
+       as Python. This function tries to be close to MediaWiki's
+       capitalize function in title.php. See :phab:`T179115` and
+       :phab:`T200357`.
     """
     first = string[:1]
     return (_first_upper_exception(first) or first.upper()) + string[1:]
@@ -334,6 +342,17 @@
     This is a reimplementation of distutils.util.strtobool due to
     :pep:`632#Migration Advice`
 
+    **Example**:
+
+    >>> strtobool('yes')
+    True
+    >>> strtobool('Off')
+    False
+    >>> strtobool('aye')
+    Traceback (most recent call last):
+    ...
+    ValueError: invalid truth value 'aye'
+
     .. versionadded:: 7.1
 
     :param val: True values are 'y', 'yes', 't', 'true', 'on', and '1';

