From f5f505f55715a9e947c567ca8f76be11b6d059a3 Mon Sep 17 00:00:00 2001
From: Markus Unterwaditzer <markus@unterwaditzer.net>
Date: Wed, 2 Jul 2014 19:14:45 +0200
Subject: [PATCH] Elaborate on caldav item queries with Radicale

---
 docs/server_support.rst   | 19 +++++++++++++------
 vdirsyncer/storage/dav.py |  8 +++++---
 2 files changed, 18 insertions(+), 9 deletions(-)

diff --git a/docs/server_support.rst b/docs/server_support.rst
index 9c11fa6..69622a5 100644
--- a/docs/server_support.rst
+++ b/docs/server_support.rst
@@ -23,12 +23,19 @@ Radicale.
   and ``end_date`` for :py:class:`vdirsyncer.storage.CaldavStorage` will have
   no or unpredicted consequences.
 
-- Versions of Radicale older than 0.9b1 don't support the necessary
-  functionality for efficient querying for all items of a collection.
-  Vdirsyncer's defaults are supposed to deal with this situation, but if you're
-  using :py:class:`vdirsyncer.storage.CaldavStorage` and set ``item_types`` to
-  an empty value (``item_types =``), these versions of Radicale will not work
-  properly.
+- `Versions of Radicale older than 0.9b1 choke on RFC-conform queries for all
+  items of a collection. <https://github.com/Kozea/Radicale/issues/143>`_.
+
+  Vdirsyncer's default value ``'VTODO, VEVENT'`` for
+  :py:class:`vdirsyncer.storage.CaldavStorage`'s ``item_types`` parameter will
+  work fine with these versions, and so will all values, except for the empty
+  one.
+
+  The empty value ``''`` will get vdirsyncer to send a single HTTP request to
+  fetch all items, instead of one HTTP request for each possible item type. As
+  the linked issue describes, old versions of Radicale expect a
+  non-RFC-compliant format for such queries, one which vdirsyncer doesn't
+  support.
 
 ownCloud
 ========
diff --git a/vdirsyncer/storage/dav.py b/vdirsyncer/storage/dav.py
index 962347b..8a9a200 100644
--- a/vdirsyncer/storage/dav.py
+++ b/vdirsyncer/storage/dav.py
@@ -444,9 +444,11 @@ class CaldavStorage(DavStorage):
     ''' + DavStorage.__doc__ + '''
     :param start_date: Start date of timerange to show, default -inf.
     :param end_date: End date of timerange to show, default +inf.
-    :param item_types: A tuple of collection types to show from the server.
-        For example, if you want to only get VEVENTs, pass ``VEVENT``.
-        Dependent on server functionality, no clientside validation of results.
+    :param item_types: Comma-separated collection types to show from the
+        server. Dependent on server functionality, no clientside validation of
+        results. The empty value ``''`` is the same as ``'VTODO, VEVENT,
+        VJOURNAL'``.
+
     '''
 
     storage_name = 'caldav'