--- a/src/pyams_utils/url.py	Sat Nov 23 01:24:11 2019 +0100
+++ b/src/pyams_utils/url.py	Sat Nov 23 14:57:24 2019 +0100
@@ -10,6 +10,19 @@
 # FOR A PARTICULAR PURPOSE.
 #
 
+"""PyAMS_utils.url module
+
+This module provides several functions, adapters and TALES extensions which can be used to
+generate object's URLs.
+
+Three kinds of URLs can be used:
+ - an absolute URL, which is the standard way to access an object via it's physical path
+ - a canonical URL; this URL is the "preferred" one used to access an object, and is typically
+   used by search engines to index contents
+ - a relative URL; some contents can use this kind of URL to get access to an object from another
+   context.
+"""
+
 from pyramid.encode import url_quote, urlencode
 from pyramid.url import QUERY_SAFE, resource_url
 from pyramid_zope_request import PyramidPublisherRequest
@@ -38,18 +51,22 @@
     'this-is-my-test'
 
     Single letters are removed from generated URLs:
+
     >>> generate_url('This word has a single a')
     'this-word-has-single'
 
     But you can define the minimum length of word:
+
     >>> generate_url('This word has a single a', min_word_length=4)
     'this-word-single'
 
     If input text contains slashes, they are replaced with hyphens:
+
     >>> generate_url('This string contains/slash')
     'this-string-contains-slash'
 
     Punctation and special characters are completely removed:
+
     >>> generate_url('This is a string with a point. And why not?')
     'this-is-string-with-point-and-why-not'
     """
@@ -64,6 +81,12 @@
 #
 
 def get_display_context(request):
+    """Get current display context
+
+    The display context can be used when we generate a page to display an object in the context
+    of another one; PyAMS_content package is using this feature to display "shared" contents as
+    is they were located inside another site or folder...
+    """
     return request.annotations.get(DISPLAY_CONTEXT, request.context)
 
 
@@ -99,12 +122,12 @@
         else:
             result += '/' + view_name
     if query:
-        qs = ''
+        qstr = ''
         if isinstance(query, str):
-            qs = '?' + url_quote(query, QUERY_SAFE)
+            qstr = '?' + url_quote(query, QUERY_SAFE)
         elif query:
-            qs = '?' + urlencode(query, doseq=True)
-        result += qs
+            qstr = '?' + urlencode(query, doseq=True)
+        result += qstr
     return result
 
 
@@ -117,6 +140,9 @@
     """
 
     def render(self, context=None, view_name=None):
+        """Extension rendering; see
+        :py:class:`ITALESExtension <pyams_utils.interfaces.tales.ITALESExtension>`
+        """
         if context is None:
             context = self.context
         return absolute_url(context, self.request, view_name)
@@ -127,7 +153,11 @@
 #
 
 def canonical_url(context, request, view_name=None, query=None):
-    """Get resource canonical URL"""
+    """Get resource canonical URL
+
+    We look for an :py:class:`ICanonicalURL <pyams_utils.interfaces.url.ICanonicalURL>` adapter;
+    if none is found, we use the absolute_url.
+    """
 
     # if we pass a string to canonical_url(), argument is returned as-is!
     if isinstance(context, str):
@@ -139,8 +169,7 @@
 
     if url_adapter is not None:
         return url_adapter.get_url(view_name, query)
-    else:
-        return absolute_url(context, request, view_name, query)
+    return absolute_url(context, request, view_name, query)
 
 
 @adapter_config(name='canonical_url', context=(Interface, Interface, Interface),
@@ -152,6 +181,9 @@
     """
 
     def render(self, context=None, view_name=None):
+        """Render TALES extension; see
+        :py:class:`ITALESExtension <pyams_utils.interfaces.tales.ITALESExtension>`
+        """
         if context is None:
             context = self.context
         return canonical_url(context, self.request, view_name)
@@ -166,13 +198,15 @@
     """Default relative URL adapter"""
 
     def get_url(self, display_context=None, view_name=None, query=None):
+        # pylint: disable=unused-argument
+        """Default adapter returns absolute URL"""
         return absolute_url(self.context, self.request, view_name, query)
 
 
 def relative_url(context, request, display_context=None, view_name=None, query=None):
     """Get resource URL relative to given context"""
     if isinstance(request, PyramidPublisherRequest):
-        request = request._request
+        request = request._request  # pylint: disable=protected-access
     if display_context is None:
         display_context = request.annotations.get(DISPLAY_CONTEXT, request.context)
     adapter = request.registry.getMultiAdapter((context, request), IRelativeURL)
@@ -189,6 +223,9 @@
     """
 
     def render(self, context=None, view_name=None, query=None):
+        """Rander TALES extension;
+        see :py:class:`ITALESExtension <pyams_utils.interfaces.tales.ITALESExtension>`
+        """
         if context is None:
             context = self.context
         return relative_url(context, self.request, view_name=view_name, query=query)