updated docs

docs/datamodel.rst

@@ -0,0 +1,63 @@
+Data Model
+====================
+
+The basic objects of the protocol as ``users``, ``contributions`` and **evaluations``.
+
+
+Users
+------------
+
+Users have ``tokens``, a number representing the amount of `ownership` of a contract,  
+and ``reputation``, a number between 0 and 1 that represents the fraction of user reputation with 
+respect to the total reputation in the system: ::
+
+   {
+       'id': 123,
+       'tokens': 11.3,
+       'reputation': 0.03
+    }
+
+
+Contributions
+-----------------
+
+A contribution has a ``contributor`` (which is the user that has made the contribution),
+a ``score`` which represents how much the contribution has been valued
+by the community, and ``engaged_reputation``, a value between 0 and 1 
+that represents the sum of the reputation of the users that have 
+evaluated the contribution. ::
+
+    {
+        'id': 12345,
+        'score': 0.30, 
+        'engaged_reputation': 0.4, 
+        'contributor' : {
+           'id': 123,
+           'tokens': 11.3,
+           'reputation': 0.03
+        }
+    }
+
+
+
+Evaluations
+----------------------
+
+An evaluation of a contribution has an ``evaluator``, which is the user that
+has made the evaluation, the ``contribution`` that the evaluation pertains to,
+and a ``value``. ::
+
+    {
+        'id': 1234545,
+        'value': 1,
+        'evaluator' : {
+           'id': 123,
+           'tokens': 11.3,
+           'reputation': 0.03
+        },
+        'contribution': {
+            'id': 12345,
+            'score': 0.30, 
+            'engaged_reputation': 0.4
+        }
+    }

docs/index.rst

@@ -11,4 +11,5 @@ Contents:
    :maxdepth: 2
 
    readme
+   datamodel
    api

restapi/views/users.py

@@ -19,11 +19,15 @@ def collection_get(request):
 
 @user_collection_service.post(validators=(get_contract,))
 def collection_post(request):
-    """Create a *new user*
+    """Create a new user.
 
-    :param tokens: the amount of tokens to assign to this user. Must be an integer or a float (like 3.14)
+    :param tokens:
+        The amount of tokens to assign to this user.
+        Must be an integer or a float (like 3.14). Not required.
 
-    :param reputation: the amount of reputation to assign to this user. Must be an integer or a float (like 3.14)
+    :param reputation:
+        The amount of reputation to assign to this user.
+        Must be an integer or a float (like 3.14). Not required.
 
     """
     user = request.contract.create_user(**request.POST)
@@ -32,14 +36,14 @@ def collection_post(request):
 
 @user_resource_service.get(validators=(get_contract,))
 def get(request):
-    """Get the user"""
+    """Get the user identified by ``id``"""
     user_id = request.matchdict['id']
     user = request.contract.get_user(user_id)
     return user_to_dict(user)
 
 
 def user_to_dict(user):
-    """return a dictionary with information about this user"""
+    """returns a dictionary with information about the user"""
     return {
         'id': user.id,
         'tokens': float(user.tokens),