From cff730e02e3752a7948430731cf912a365c281ad Mon Sep 17 00:00:00 2001
From: Markus Unterwaditzer <markus@unterwaditzer.net>
Date: Sun, 9 Mar 2014 17:33:17 +0100
Subject: [PATCH] More documentation

---
 vdirsyncer/storage/base.py       | 19 ++++++++++++-------
 vdirsyncer/storage/dav/base.py   | 12 +++++++++---
 vdirsyncer/storage/dav/caldav.py |  6 +++++-
 vdirsyncer/storage/filesystem.py |  9 ++++++++-
 4 files changed, 34 insertions(+), 12 deletions(-)

diff --git a/vdirsyncer/storage/base.py b/vdirsyncer/storage/base.py
index 229b65c..06c88e2 100644
--- a/vdirsyncer/storage/base.py
+++ b/vdirsyncer/storage/base.py
@@ -30,9 +30,11 @@ class Storage(object):
 
     Terminology:
       - UID: Global identifier of the item, across storages.
-      - HREF: Per-storage identifier of item, might be UID.
+      - HREF: Per-storage identifier of item, might be UID. The reason items
+          aren't just referenced by their UID is because the CalDAV and CardDAV
+          specifications make this imperformant to implement.
       - ETAG: Checksum of item, or something similar that changes when the
-              object does.
+          object does.
 
     :param collection: If None, the given URL or path is already directly
         referring to a collection. Otherwise it will be treated as a basepath
@@ -42,13 +44,16 @@ class Storage(object):
     fileext = '.txt'
     _repr_attributes = ()
 
-    def __init__(self, item_class=Item):
-        self.item_class = item_class
-
     @classmethod
     def discover(cls, **kwargs):
-        '''Discover collections given a basepath to many collections.
-        :returns: Iterable of storages.'''
+        '''
+        Discover collections given a basepath or -URL to many collections.
+        :param **kwargs: Keyword arguments to additionally pass to the storage
+            instances returned. You shouldn't pass `collection` here, otherwise
+            TypeError will be raised.
+        :returns: Iterable of storages which represent the discovered
+            collections, all of which are passed kwargs during initialization.
+        '''
         raise NotImplementedError()
 
     def _get_href(self, uid):
diff --git a/vdirsyncer/storage/dav/base.py b/vdirsyncer/storage/dav/base.py
index 42aa759..9bc7090 100644
--- a/vdirsyncer/storage/dav/base.py
+++ b/vdirsyncer/storage/dav/base.py
@@ -16,12 +16,16 @@ from lxml import etree
 
 class DavStorage(Storage):
 
+    # the file extension of items. Useful for testing against radicale.
     fileext = None
+    # mimetype of items
     item_mimetype = None
+    # The expected header for resource validation.
     dav_header = None
+    # XML to use when fetching multiple hrefs.
     get_multi_template = None
+    # The LXML query for extracting results in get_multi
     get_multi_data_query = None
-    list_xml = None
 
     _session = None
     _repr_attributes = ('url', 'username')
@@ -29,12 +33,13 @@ class DavStorage(Storage):
     def __init__(self, url, username='', password='', collection=None,
                  verify=True, auth='basic', useragent='vdirsyncer', **kwargs):
         '''
-        :param url: Direct URL for the CalDAV collection. No autodiscovery.
+        :param url: Base URL or an URL to a collection. Autodiscovery should be
+            done via :py:meth:`DavStorage.discover`.
         :param username: Username for authentication.
         :param password: Password for authentication.
         :param verify: Verify SSL certificate, default True.
         :param auth: Authentication method, from {'basic', 'digest'}, default
-                     'basic'.
+            'basic'.
         :param useragent: Default 'vdirsyncer'.
         '''
         super(DavStorage, self).__init__(**kwargs)
@@ -56,6 +61,7 @@ class DavStorage(Storage):
             url = urlparse.urljoin(url, collection)
         self.url = url.rstrip('/') + '/'
         self.parsed_url = urlparse.urlparse(self.url)
+        self.collection = collection
 
         headers = self._default_headers()
         headers['Depth'] = 1
diff --git a/vdirsyncer/storage/dav/caldav.py b/vdirsyncer/storage/dav/caldav.py
index 2a5de6e..b7990b7 100644
--- a/vdirsyncer/storage/dav/caldav.py
+++ b/vdirsyncer/storage/dav/caldav.py
@@ -21,9 +21,9 @@ class CaldavStorage(DavStorage):
     fileext = '.ics'
     item_mimetype = 'text/calendar'
     dav_header = 'calendar-access'
+
     start_date = None
     end_date = None
-    item_types = None
 
     get_multi_template = '''<?xml version="1.0" encoding="utf-8" ?>
         <C:calendar-multiget xmlns:D="DAV:"
@@ -42,6 +42,10 @@ class CaldavStorage(DavStorage):
         '''
         :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: The item types to show from the server. Dependent on
+            server functionality, no clientside validation of results. This
+            currently only affects the `list` method, but this shouldn't cause
+            problems in the normal usecase.
         '''
         super(CaldavStorage, self).__init__(**kwargs)
         if isinstance(item_types, str):
diff --git a/vdirsyncer/storage/filesystem.py b/vdirsyncer/storage/filesystem.py
index 5b9a8c6..eeedad3 100644
--- a/vdirsyncer/storage/filesystem.py
+++ b/vdirsyncer/storage/filesystem.py
@@ -24,7 +24,14 @@ class FilesystemStorage(Storage):
     def __init__(self, path, fileext, collection=None, encoding='utf-8',
                  **kwargs):
         '''
-        :param path: Absolute path to a *collection* inside a vdir.
+        :param path: Absolute path to a vdir or collection, depending on the
+            collection parameter (see
+            :py:class:`vdirsyncer.storage.base.Storage`).
+        :param fileext: The file extension to use (e.g. `".txt"`). Contained in
+            the href, so if you change the file extension after a sync, this
+            will trigger a re-download of everything (but *should* not cause
+            data-loss of any kind).
+        :param encoding: File encoding for items.
         '''
         super(FilesystemStorage, self).__init__(**kwargs)
         if collection is not None: