From 070a39a51d2b85d4bda9a65f85ecfe1b0b0d76af Mon Sep 17 00:00:00 2001
From: Unrud <unrud@openaliasbox.org>
Date: Fri, 16 Jun 2017 23:16:19 +0200
Subject: [PATCH] Improve documentation

---
 radicale/rights.py  |  6 +++++-
 radicale/storage.py |  6 ++++--
 radicale/web.py     | 12 ++++++++++++
 3 files changed, 21 insertions(+), 3 deletions(-)

diff --git a/radicale/rights.py b/radicale/rights.py
index 28c8132..dcbf0e3 100644
--- a/radicale/rights.py
+++ b/radicale/rights.py
@@ -79,7 +79,11 @@ class BaseRights:
     def authorized(self, user, path, permission):
         """Check if the user is allowed to read or write the collection.
 
-        If the user is empty, check for anonymous rights.
+        If ``user`` is empty, check for anonymous rights.
+
+        ``path`` is sanitized.
+
+        ``permission`` is "r" or "w".
 
         """
         raise NotImplementedError
diff --git a/radicale/storage.py b/radicale/storage.py
index 123154e..815d2c3 100644
--- a/radicale/storage.py
+++ b/radicale/storage.py
@@ -334,14 +334,14 @@ class BaseCollection:
     def discover(cls, path, depth="0"):
         """Discover a list of collections under the given ``path``.
 
+        ``path`` is sanitized.
+
         If ``depth`` is "0", only the actual object under ``path`` is
         returned.
 
         If ``depth`` is anything but "0", it is considered as "1" and direct
         children are included in the result.
 
-        The ``path`` is relative.
-
         The root collection "/" must always exist.
 
         """
@@ -373,6 +373,8 @@ class BaseCollection:
     def create_collection(cls, href, collection=None, props=None):
         """Create a collection.
 
+        ``href`` is the sanitized path.
+
         If the collection already exists and neither ``collection`` nor
         ``props`` are set, this method shouldn't do anything. Otherwise the
         existing collection must be replaced.
diff --git a/radicale/web.py b/radicale/web.py
index bc8364c..d3b96c2 100644
--- a/radicale/web.py
+++ b/radicale/web.py
@@ -67,6 +67,18 @@ class BaseWeb:
         self.configuration = configuration
         self.logger = logger
 
+    def get(self, environ, base_prefix, path, user):
+        """GET request.
+
+        ``base_prefix`` is sanitized and never ends with "/".
+
+        ``path`` is sanitized and always starts with "/.web"
+
+        ``user`` is empty for anonymous users.
+
+        """
+        raise NotImplementedError
+
 
 class NoneWeb(BaseWeb):
     def get(self, environ, base_prefix, path, user):