Merge pull request #759 from andrewcbennett/665_doc_updates

Improve relativedelta documentation

changelog.d/759.doc.rst

@@ -0,0 +1 @@
+Improved the documentation for the ``relativedelta.relativedelta`` class. Contributed by @andrewcbennett (gh pr #759)

dateutil/relativedelta.py

@@ -17,8 +17,12 @@
 
 class relativedelta(object):
     """
-    The relativedelta type is based on the specification of the excellent
-    work done by M.-A. Lemburg in his
+    The relativedelta type is designed to be applied to an existing datetime and
+    can replace specific components of that datetime, or represents an interval
+    of time.
+
+    It is based on the specification of the excellent work done by M.-A. Lemburg
+    in his
     `mx.DateTime <https://www.egenix.com/products/python/mxBase/mxDateTime/>`_ extension.
     However, notice that this type does *NOT* implement the same algorithm as
     his work. Do *NOT* expect it to behave like mx.DateTime's counterpart.
@@ -45,13 +49,15 @@ class relativedelta(object):
             with the information in the relativedelta.
 
         weekday: 
-            One of the weekday instances (MO, TU, etc). These
-            instances may receive a parameter N, specifying the Nth
-            weekday, which could be positive or negative (like MO(+1)
-            or MO(-2). Not specifying it is the same as specifying
-            +1. You can also use an integer, where 0=MO. Notice that
-            if the calculated date is already Monday, for example,
-            using MO(1) or MO(-1) won't change the day.
+            One of the weekday instances (MO, TU, etc) available in the
+            relativedelta module. These instances may receive a parameter N,
+            specifying the Nth weekday, which could be positive or negative
+            (like MO(+1) or MO(-2)). Not specifying it is the same as specifying
+            +1. You can also use an integer, where 0=MO. This argument is always
+            relative e.g. if the calculated date is already Monday, using MO(1)
+            or MO(-1) won't change the day. To effectively make it absolute, use
+            it in combination with the day argument (e.g. day=1, MO(1) for first
+            Monday of the month).
 
         leapdays:
             Will add given days to the date found, if year is a leap
@@ -82,9 +88,12 @@ class relativedelta(object):
 
     For example
 
+    >>> from datetime import datetime
+    >>> from dateutil.relativedelta import relativedelta, MO
     >>> dt = datetime(2018, 4, 9, 13, 37, 0)
     >>> delta = relativedelta(hours=25, day=1, weekday=MO(1))
-    datetime(2018, 4, 2, 14, 37, 0)
+    >>> dt + delta
+    datetime.datetime(2018, 4, 2, 14, 37)
 
     First, the day is set to 1 (the first of the month), then 25 hours
     are added, to get to the 2nd day and 14th hour, finally the