Update documentation and README

README.rst

@@ -109,6 +109,43 @@ Here is a simple usage example:
     result = db.aql.execute('FOR s IN students RETURN s')
     print([student['name'] for student in result])
 
+
+Here is another example using graphs:
+
+.. code-block:: python
+
+    from arango import ArangoClient
+
+    client = ArangoClient()
+
+    # Define a new graph
+    graph = client.db('my_database').create_graph('schedule')
+    profs = graph.create_vertex_collection('professors')
+    courses = graph.create_vertex_collection('courses')
+    teaches = graph.create_edge_definition(
+        name='teaches',
+        from_collections=['professors'],
+        to_collections=['courses']
+    )
+
+    # Insert vertices into the graph
+    profs.insert({'_key': 'anna', 'name': 'Anna Parker'})
+    courses.insert({'_key': 'MAT101', 'name': 'Calculus I'})
+    courses.insert({'_key': 'STA101', 'name': 'Statistics I'})
+
+    # Insert edges into the graph
+    teaches.insert({'_from': 'professors/anna', '_to': 'courses/MAT101'})
+    teaches.insert({'_from': 'professors/anna', '_to': 'courses/STA101'})
+
+    # Traverse the graph in outbound direction, breath-first
+    traversal_results = graph.traverse(
+        start_vertex='professors/anna',
+        strategy='bfs',
+        direction='outbound'
+    )
+    print(traversal_results)
+
+
 Please read the full `API documentation`_ for more details!
 
 .. _API documentation:

arango/batch.py

@@ -154,13 +154,13 @@ def commit(self):
             self._batch_jobs = []
 
     def clear(self):
-        """Clear the API requests queue and discard any batch job pointers.
+        """Clear the requests queue and discard pointers to batch jobs issued.
 
-        :returns: the number of API requests and batch job pointers discarded
+        :returns: the number of requests (and batch job pointers) discarded
         :rtype: int
 
         .. warning::
-            This method will orphan any batch jobs that were issues
+            This method will orphan any batch jobs that were issued
         """
         count = len(self._requests)
         self._requests = []