Add doc to period class

Author: Mauko Quiroga

openfisca_core/periods/period_.py

@@ -2,7 +2,7 @@
 
 import calendar
 
-from openfisca_core import periods
+from openfisca_core.periods import Instant
 
 from .date_unit import DateUnit
 
@@ -15,20 +15,24 @@ class Period(tuple):
     (year, month, day) triple, and where size is an integer > 1.
 
     Since a period is a triple it can be used as a dictionary key.
+
+    Examples:
+        >>> instant = Instant((2021, 9, 1))
+        >>> period = Period((DateUnit.YEAR.value, instant, 3))
+
+        >>> repr(Period)
+        "<class 'openfisca_core.periods.period_.Period'>"
+
+        >>> repr(period)
+        "<Period(('year', <Instant(2021, 9, 1)>, 3))>"
+
+        >>> str(period)
+        'year:2021-09:3'
+
     """
 
-    def __repr__(self):
-        """
-        Transform period to to its Python representation as a string.
-
-        >>> repr(period('year', 2014))
-        "Period(('year', Instant((2014, 1, 1)), 1))"
-        >>> repr(period('month', '2014-2'))
-        "Period(('month', Instant((2014, 2, 1)), 1))"
-        >>> repr(period('day', '2014-2-3'))
-        "Period(('day', Instant((2014, 2, 3)), 1))"
-        """
-        return '{}({})'.format(self.__class__.__name__, super(Period, self).__repr__())
+    def __repr__(self) -> str:
+        return f"<{self.__class__.__name__}({super().__repr__()})>"
 
     def __str__(self):
         """