From 78ed569b35e330bd1e5cc6997f339e2a21cad065 Mon Sep 17 00:00:00 2001
From: James Turk <james.p.turk@gmail.com>
Date: Fri, 23 Oct 2009 14:43:17 -0400
Subject: [PATCH] doc updates for sphinx

---
 README.rst        | 14 +++++++++++++-
 layar/__init__.py | 33 ++++++++++++++++++++++-----------
 2 files changed, 35 insertions(+), 12 deletions(-)

diff --git a/README.rst b/README.rst
index 0d5e9c7..e19905b 100644
--- a/README.rst
+++ b/README.rst
@@ -52,7 +52,7 @@ It is possible to serve as many layers as you desire from a single Layar endpoin
 and should return a queryset of the objects for :class:`LayarView` to paginate and return.
 
 :func:`poi_from_LAYERNAME_item` is called on each item being returned, and should convert items
-into :class:`POI` objects.
+into :class:`layar.POI` objects.
 
 It is usually best to then create an instance of your derived class in your application's ``views.py``
 
@@ -86,3 +86,15 @@ In urls.py it is then necessary to map a URL directly to ``busstop_layar``::
     urlpatterns = patterns('',
         url(r'^layar_endpoint/$', 'myapp.views.busstop_layar'),
     )
+
+Additional Settings
+-------------------
+
+Your :class:`LayarView`-derived class can also set a number of options.  These options should be suitable for most purposes as Layar doesn't display more than 50 points, but are available should you for any reason need to change them.
+
+``results_per_page``
+    controls the number of results returned at once (default: 15)
+``max_results``
+    controls the maximum number of results across all pages (default: 50)
+``verify_hash``
+    set to False to disable hash verification (useful for testing, shouldn't be False in production)
diff --git a/layar/__init__.py b/layar/__init__.py
index 35700f0..863f0dd 100644
--- a/layar/__init__.py
+++ b/layar/__init__.py
@@ -79,20 +79,31 @@ class LayarView(object):
 
         To add a layar it is necessary to write two functions:
             ``get_LAYERNAME_queryset``
-                return a queryset of objects to be used to build the layer
-            ``poi_from_LAYERNAME_item``
-                convert an item of whatever type is returned by
-                get_LAYARNAME_queryset into a ``POI`` object
+                This function is passed latitude, longitude, radius,
+                radio_option, search_query, and slider_value parameters.
+
+                radio_option, search_query, and slider_value may be None
+                depending on how you've configured your widgets on layar.com
+
+                **Note:** It is strongly recommended that you make this function
+                accept **kwargs for maximum compatibility
+
+            ``poi_from_LAYERNAME_item(item)``
+                convert an item of whatever type is returned by 
+                :func:`get_LAYARNAME_queryset` into a ``POI`` object
 
         This separation allows LayarView to handle pagination correctly.
 
-        Options:
-            ``results_per_page``
-                defaults to the Layar-recommended 15
-            ``max_results``
-                defaults to the Layar-recommended 50
-            ``verify_hash``
-                set to False to disable hash verification (useful for testing)
+        Your derived class can also set a number of options.  The defaults
+        should be suitable for most purposes as Layar doesn't display more
+        than 50 points.
+
+        ``results_per_page``
+            controls the number of results returned at once (default: 15)
+        ``max_results``
+            controls the maximum number of results across all pages (default: 50)
+        ``verify_hash``
+            set to False to disable hash verification (useful for testing)
     '''
 
     results_per_page = 15