--- a/src/pyams_utils/date.py	Tue Nov 15 10:43:55 2016 +0100
+++ b/src/pyams_utils/date.py	Fri Nov 18 15:28:54 2016 +0100
@@ -31,10 +31,14 @@
     
     Dates are always assumed to be stored in GMT timezone
     
-    @param value: input date to convert to unicode
-    @type value: date or datetime
-    @return: input date converted to unicode
-    @rtype: unicode
+    :param date value: input date to convert to unicode
+    :return: unicode; input date converted to unicode
+
+    >>> from datetime import datetime
+    >>> from pyams_utils.date import unidate
+    >>> value = datetime(2016, 11, 15, 10, 13, 12)
+    >>> unidate(value)
+    '2016-11-15T10:13:12+00:00'
     """
     if value is not None:
         value = gmtime(value)
@@ -47,10 +51,12 @@
     
     Dates are always assumed to be stored in GMT timezone
     
-    @param value: unicode date to be parsed
-    @type value: unicode
-    @return: the specified value, converted to datetime
-    @rtype: datetime
+    :param str value: unicode date to be parsed
+    :return: datetime; the specified value, converted to datetime
+
+    >>> from pyams_utils.date import parse_date
+    >>> parse_date('2016-11-15T10:13:12+00:00')
+    datetime.datetime(2016, 11, 15, 10, 13, 12, tzinfo=<StaticTzInfo 'GMT'>)
     """
     if value is not None:
         return gmtime(parseDatetimetz(value))
@@ -60,10 +66,19 @@
 def date_to_datetime(value):
     """Get datetime value converted from a date or datetime object
     
-    @param value: a date or datetime value to convert
-    @type value: date or datetime
-    @return: input value converted to datetime
-    @rtype: datetime
+    :param date/datetime value: a date or datetime value to convert
+    :return: datetime; input value converted to datetime
+
+    >>> from datetime import date, datetime
+    >>> from pyams_utils.date import date_to_datetime
+    >>> value = date(2016, 11, 15)
+    >>> date_to_datetime(value)
+    datetime.datetime(2016, 11, 15, 0, 0)
+    >>> value = datetime(2016, 11, 15, 10, 13, 12)
+    >>> value
+    datetime.datetime(2016, 11, 15, 10, 13, 12)
+    >>> date_to_datetime(value) is value
+    True
     """
     if not value:
         return None
@@ -80,7 +95,21 @@
 
 
 def format_date(value, format=EXT_DATE_FORMAT, request=None):
-    """Format given date with the given format"""
+    """Format given date with the given format
+
+    :param datetime value: the value to format
+    :param str format: a format string to use by `strftime` function
+    :param request: the request from which to extract localization info for translation
+    :return: str; input datetime converted to given format
+
+    >>> from datetime import datetime
+    >>> from pyams_utils.date import format_date, SH_DATE_FORMAT
+    >>> value = datetime(2016, 11, 15, 10, 13, 12)
+    >>> format_date(value)
+    'on 15/11/2016'
+    >>> format_date(value, SH_DATE_FORMAT)
+    '15/11/2016'
+    """
     if not value:
         return '--'
     if request is None:
@@ -90,12 +119,30 @@
 
 
 def format_datetime(value, format=EXT_DATETIME_FORMAT, request=None):
-    """Format given datetime with the given format"""
+    """Format given datetime with the given format including time
+
+    :param datetime value: the value to format
+    :param str format: a format string to use by `strftime` function
+    :param request: request; the request from which to extract localization info for translation
+    :return: str; input datetime converted to given format
+
+    >>> from datetime import datetime
+    >>> from pyams_utils.date import format_datetime, SH_DATETIME_FORMAT
+    >>> value = datetime(2016, 11, 15, 10, 13, 12)
+    >>> format_datetime(value)
+    'on 15/11/2016 at 10:13'
+    >>> format_datetime(value, SH_DATETIME_FORMAT)
+    '15/11/2016 - 10:13'
+    """
     return format_date(value, format, request)
 
 
 def get_age(value, request=None):
-    """Get age of a given datetime (including timezone) compared to current datetime (in UTC)"""
+    """Get 'human' age of a given datetime (including timezone) compared to current datetime (in UTC)
+
+    :param datetime value: input datetime to be compared with current datetime
+    :return: str; the delta value, converted to months, weeks, days, hours or minutes
+    """
     if request is None:
         request = check_request()
     translate = request.localizer.translate
@@ -122,7 +169,12 @@
 
 
 def get_duration(v1, v2=None, request=None):
-    """Get delta as string between two dates
+    """Get 'human' delta as string between two dates
+
+    :param datetime v1: start date
+    :param datetime v2: end date, or current date (in UTC) if None
+    :param request: the request from which to extract localization infos
+    :return: str; approximate delta between the two input dates
 
     >>> from datetime import datetime
     >>> from pyams_utils.date import get_duration
@@ -134,6 +186,7 @@
     '10 months'
 
     Dates order is not important:
+
     >>> get_duration(date2, date1, request)
     '10 months'
     >>> date2 = datetime(2014, 11, 10)
@@ -144,6 +197,7 @@
     '6 days'
 
     For durations lower than 2 days, duration also display hours:
+
     >>> date1 = datetime(2015, 1, 1)
     >>> date2 = datetime(2015, 1, 2, 15, 10, 0)
     >>> get_duration(date1, date2, request)