From a9345412f870787fc885a5ef1a09b2c699f157d8 Mon Sep 17 00:00:00 2001
From: Julio Biason <julio.biason@gmail.com>
Date: Fri, 18 Apr 2014 22:42:31 -0300
Subject: [PATCH] documentation

---
 doc/client/flow/voting.rst  | 71 +++++++++++++++++++++++++++++++++++++
 doc/client/index.rst        | 11 ++++++
 doc/client/voting.rst       |  6 ++++
 luncho/blueprints/voting.py |  2 +-
 luncho/exceptions.py        |  2 +-
 5 files changed, 90 insertions(+), 2 deletions(-)
 create mode 100644 doc/client/flow/voting.rst
 create mode 100644 doc/client/voting.rst

diff --git a/doc/client/flow/voting.rst b/doc/client/flow/voting.rst
new file mode 100644
index 0000000..0fc59fc
--- /dev/null
+++ b/doc/client/flow/voting.rst
@@ -0,0 +1,71 @@
+Voting
+=======
+
+A typical voting/check results flow would be:
+
+1. Get the token:
+
+   .. sourcecode:: http
+
+      POST /token/
+      { "user": "username", "password": "userPassword" }
+
+   Remember: the token is valid for a whole day. You can still request the
+   token, but the response will always be the same for the whole day.
+
+   We suggest keeping the user credentials and token stored somewhere. If any
+   request you receive a 
+
+   .. sourcecode:: http
+
+      HTTP/1.1 404 Not Found
+      Content-Type: text/json
+
+      { "status": "ERROR",
+        "code": "UserNotFound",
+        "User not found (via token)" }
+
+   then request a new token.
+
+2. Once you have the token, you can request the user groups (or store then and
+   offer a "Refresh" button somewhere):
+
+   .. sourcecode:: http
+
+      GET /group/
+
+   This will return all groups in which the user is a member.
+
+3. For each group, you can request the current voting results:
+
+   .. sourcecode:: http
+
+      GET /vote/{group_id}/
+
+4. The first result with *always* be the place with more points. The avoid
+   requesting the places just to show the name, the name for each place will
+   be returned in the results.
+
+   Keep in mind that once every member of a group voted, the voting will have
+   a `closed` property set to `true`. In this case, it means there will be no
+   change in the results and the place has been picked.
+
+5. To vote, you'll need to display the current places for the group. For that,
+   request the places for the group:
+
+   .. sourcecode:: http
+
+      GET /group/{group_id}/places/
+
+   Then let the user pick up to 3 places, with ordering.
+
+6. Once the user picks the places, cast the vote:
+
+   .. sourcecode:: http
+
+      POST /vote/{group_id}/
+
+      { "choices": [ <first place id>, <second place id>, ... ] }
+
+7. Once you get a success response, return to the list of groups. You can even
+   re-request the current results, just to be sure.
diff --git a/doc/client/index.rst b/doc/client/index.rst
index 762e7b5..32c5689 100644
--- a/doc/client/index.rst
+++ b/doc/client/index.rst
@@ -66,6 +66,16 @@ Redirects
 All URLs must end with "/"; if you forget to add them in the URL, you'll
 receive a redirect to the path with "/".
 
+Flow
+=====
+
+Here are some expected typical request flows:
+
+.. toctree::
+   :maxdepth: 3
+
+   flow/voting
+
 API
 ====
 
@@ -75,3 +85,4 @@ API
    users_and_tokens
    places
    groups
+   voting
diff --git a/doc/client/voting.rst b/doc/client/voting.rst
new file mode 100644
index 0000000..2d8e3ca
--- /dev/null
+++ b/doc/client/voting.rst
@@ -0,0 +1,6 @@
+Voting
+=======
+
+.. autoflask:: luncho.server:app
+   :blueprints: voting
+   :undoc-endpoints: static, show_api
diff --git a/luncho/blueprints/voting.py b/luncho/blueprints/voting.py
index b895d43..c769067 100644
--- a/luncho/blueprints/voting.py
+++ b/luncho/blueprints/voting.py
@@ -129,7 +129,7 @@ def cast_vote(group_id):
 
     :status 200: Success
     :status 400: Request MUST be in JSON format
-        (:pyu:class:`RequestMustBeJSONException`)
+        (:py:class:`RequestMustBeJSONException`)
     :status 400: Missing fields
         (:py:class:`MissingFieldsException`)
     :status 403: User is not member of this group
diff --git a/luncho/exceptions.py b/luncho/exceptions.py
index bf3a951..1f57cde 100644
--- a/luncho/exceptions.py
+++ b/luncho/exceptions.py
@@ -70,7 +70,7 @@ class InvalidTokenException(LunchoException):
 
     ..sourcecode:: http
 
-       HTTP/1.1 400 Bad REquest
+       HTTP/1.1 400 Bad Request
        Content-Type: text/json
 
        { "status": "ERROR", "message": "Invalid token" }