From bcc3164cd7e5d7efa4d9b7e5b04f49d3c1f3207b Mon Sep 17 00:00:00 2001
From: Stefan B <Stefan.bie@live.de>
Date: Sun, 20 Nov 2016 16:01:11 +0100
Subject: [PATCH] - add more docs

---
 provdbconnector/prov_db.py | 87 +++++++++++++++++++++++++++++++++++++-
 1 file changed, 86 insertions(+), 1 deletion(-)

diff --git a/provdbconnector/prov_db.py b/provdbconnector/prov_db.py
index 0de8cf7..4fb41b2 100644
--- a/provdbconnector/prov_db.py
+++ b/provdbconnector/prov_db.py
@@ -212,6 +212,22 @@ def get_document_as_prov(self, document_id=None):
     def save_element(self, prov_element, bundle_id=None):
         """
         Saves a activity, entity, agent
+
+        .. code:: python
+
+
+            doc = ProvDocument()
+
+            agent       = doc.agent("ex:yourAgent")
+            activity    = doc.activity("ex:yourActivity")
+            entity      = doc.entity("ex:yourEntity")
+
+            # Save the elements
+            agent_id = prov_db.save_element(agent)
+            activity_id = prov_db.save_element(activity)
+            entity_id = prov_db.save_element(entity)
+
+
         :param prov_element: The ProvElement
         :type prov_element: prov.model.ProvElement
         :param bundle_id:
@@ -230,11 +246,28 @@ def save_element(self, prov_element, bundle_id=None):
             self._create_bundle_association([prov_element], prov_element.bundle.identifier)
 
         return prov_element.identifier
+
     def get_elements(self, prov_element_cls):
         """
         Return a document that contains the requested type
+
+        .. code:: python
+
+            from prov.model import ProvEntity, ProvAgent, ProvActivity
+
+            document_with_all_entities = prov_db.get_elements(ProvEntity)
+            document_with_all_agents = prov_db.get_elements(ProvAgent)
+            document_with_all_activities = prov_db.get_elements(ProvActivity)
+
+            print(document_with_all_entities)
+            print(document_with_all_agents)
+            print(document_with_all_activities)
+
+
         :param prov_element_cls:
-        :return:
+        :return: Prov document
+        :rtype prov.model.ProvDocument
+
         """
         if prov_element_cls is ProvAgent:
             prov_type = PROV_AGENT
@@ -259,6 +292,16 @@ def get_elements(self, prov_element_cls):
     def get_element(self, identifier):
         """
         Get a element (activity, agent, entity) from the database
+
+        .. code:: python
+
+            doc = ProvDocument()
+
+            identifier = QualifiedName(doc, "ex:yourAgent")
+
+            prov_element = prov_db.get_element(identifier)
+
+
         :param identifier:
         :type identifier: prov.model.QualifiedName
         :return: A prov Element class
@@ -291,6 +334,18 @@ def save_record(self, prov_record, bundle_id=None):
         """
         Saves a realtion or a element (Entity, Agent or Activity)
 
+        .. code:: python
+
+
+            doc = ProvDocument()
+
+            agent       = doc.agent("ex:Alice")
+            ass_rel     = doc.association("ex:Alice", "ex:Bob")
+
+            # Save the elements
+            agent_id = prov_db.save_record(agent)
+            relation_id = prov_db.save_record(ass_rel)
+
         :param prov_record: The prov record
         :type prov.model.ProvRecord
         :param bundle_id: The bundle id that you got back if you created a bundle or document
@@ -365,6 +420,15 @@ def _parse_record(prov_bundle, raw_record):
     def get_bundle(self,identifier):
         """
         Returns the whole bundle for the provided identifier
+
+        .. code:: python
+            doc = ProvDocument()
+            bundle_name = doc.valid_qualified_name("ex:YourBundleName")
+            # get the bundle
+            prov_bundle = prov_db.get_bundle(bundle_name)
+            doc.add_bundle(prov_bundle)
+
+
         :param identifier: The identifier
         :type identifier: prov.model.QualifiedName
         :return: The prov bundle instance
@@ -391,6 +455,15 @@ def get_bundle(self,identifier):
     def save_bundle(self,prov_bundle):
         """
         Public method to save a bundle
+
+        .. code:: python
+
+            doc = ProvDocument()
+
+            bundle = doc.bundle("ex:bundle1")
+            # Save the bundle
+            prov_db.save_bundle(bundle)
+
         :param prov_bundle:
         :type prov_bundle: prov.model.ProvBundle
         :return:
@@ -435,6 +508,18 @@ def save_relation(self, prov_relation, bundle_id=None):
         """
         Saves a relation between 2 nodes that are already in the database.
 
+        .. code:: python
+
+            doc = ProvDocument()
+
+            activity    = doc.activity("ex:yourActivity")
+            entity      = doc.entity("ex:yourEntity")
+            wasGeneratedBy = entity.wasGeneratedBy("ex:yourAgent")
+
+            # Save the elements
+            rel_id = prov_db.save_relation(wasGeneratedBy)
+
+
         :param prov_relation: The ProvRelation instance
         :type prov_relation: ProvRelation
         :param bundle_id