Added some more content to documentation

doc/wrappers.rst

@@ -26,6 +26,12 @@ All operations happen *synchronously*, meaning that they block until the Modelve
 Note that some functions are only applicable in a certain *context*.
 In practice, this means that you should first issue the *init* and *login* operations, as otherwise your connection with the Modelverse will not have started up yet.
 
+For each function, we provide an example to indicate how this operation can be used.
+In these first examples, assume that all referenced elements are present, all permissions are granted, etc.
+For each exception, then, we provide an example where it can occur.
+In these examples, the problem is often caused by an non-existing element or unsatisfied permissions.
+From the example, it should be clear what the problem is.
+
 Functions
 ^^^^^^^^^
 
@@ -56,9 +62,9 @@ Functions
 
    Examples:
 
-   To login as user yentl, with the specified password:
+   To login as user user1, with the specified password:
    .. code::
-      >> login("yentl", "my_password")
+      >> login("user1", "my_password")
 
 .. function:: model_add(model_name, metamodel_name, model_code=None)
 
@@ -136,9 +142,9 @@ Functions
 
    .. code::
       >> model_list_full()
-      [("my_pn", "PetriNets", "yentl", "users", "200"), 
-       ("my_pn2", "PetriNets", "yentl", "users", "200"),
-       ("PetriNets", "SimpleClassDiagrams", "yentl", "users", "211"),
+      [("my_pn", "PetriNets", "user1", "users", "200"), 
+       ("my_pn2", "PetriNets", "user1", "users", "200"),
+       ("PetriNets", "SimpleClassDiagrams", "user1", "users", "211"),
        ("SimpleClassDiagrams", "SimpleClassDiagrams", "admin", "admin", "211")]
 
 .. function:: verify(model_name)
@@ -340,10 +346,33 @@ Functions
    Executes the model transformation operation *operation_name*.
    Identical to *transformation_execute_AL*.
 
+   Examples:
+
+   To execute a model transformation on a PetriNets instance, thereby putting the result in a different model:
+   .. code::
+      >> transformation_execute_MT("pn_simulate", {"pn": "my_pn"}, {"pn": "my_simulated_pn"})
+
+    To execute a model transformation which prompts the user:
+    .. code::
+       >> def callback(value):
+       >>     print(value)
+       >>     return raw_input()
+       >> transformation_execute_MT("pn_simulate_prompt", {"pn": "my_pn"}, {"pn": "my_simulated_pn"}, callback)
+
 .. function:: transformation_list()
 
    Returns a list of all operations specified in the Modelverse, together with their type.
 
+   Examples:
+
+   To fetch a list of all transformations and their type of operation:
+   .. code::
+      >> transformation_list()
+      [("pn_simulate", "ModelTransformation"),
+       ("pn_reachability", "ActionLanguage"),
+       ("pn_simulate_prompt", "ModelTransformation"),
+       ("pn_refine", "ManualOperation")]
+
 .. function:: process_execute(process_name, prefix, callbacks)
 
    Execute the process model stored as *process_name*.
@@ -352,64 +381,185 @@ Functions
    Optionally, a dictionary of *callbacks* can be defined with as key the operation that is being executed, and value the actual callback.
    The callbacks must be similarly defined just like how they were defined in the individual *transformation_execute* operations.
 
+   Examples:
+
+   To execute a process model for the power window example:
+   .. code::
+      >> process_execute("pm_powerwindow", "pw_")
+
+   To execute a process model for the power window example, which requires user input for some operations:
+   .. code::
+      >> def refine_architecture():
+      >>     # Do some operation on the architecture model here
+      >>     node1 = instantiate(None, "Node")
+      >>     node2 = instantiate(None, "Node")
+      >>     instantiate(None, "Connection", (node1, node2))
+      >> def refine_control():
+      >>     # Do some operation on the control model here
+      >>     s1 = instantiate(None, "State")
+      >>     s2 = instantiate(None, "State")
+      >>     instantiate(None, "Transition", (s1, s2))
+      >> def refine_query():
+      >>     # Do some operation on the safety query model here
+      >>     p1 = instantiate(None, "Place")
+      >>     attr_assign(None, p1, "tokens", 2)
+      >> process_execute("pm_powerwindow", "pw_", {"refine_plant": refine_plant, "refine_control": refine_control, "refine_query": refine_query})
+
 .. function:: permission_modify(model_name, permissions)
 
    Change the permissions of *model_name* to *permissions*.
    The permissions is a string of three characters, each between 0 and 2.
    The format is similar to the UNIX permission system: the leftmost character is the permission for the owning user, the middle character for members of the ownin group, and the rightmost character for all other users.
    Character 0 signifies no access, 1 read-only access, and 2 full read/write access.
+   Note that changing permissions trickle down to the instances as well: if the metamodel is no longer readable to the user, all models conforming to it become unreadable in this specific context.
+
+   Examples:
+
+   To modify the permissions of the PetriNets metamodel, allowing only the owner to read and write to it:
+   .. code::
+      >> permission_modify("PetriNets", "200")
+
+   To modify the permissions of a PetriNets model, granting everyone read/write access:
+   .. code::
+      >> permission_modify("PetriNets", "222")
 
 .. function:: permission_owner(model_name, owner)
 
    Change the owner of the model *model_name* to *owner*.
+   Changing permissions trickles down to the instances as well: if the metamodel is no longer readable to the user, all models conforming to it become unreadable in this specific context.
+
+   Examples:
+
+   To change the owning user of the PetriNets metamodel to user2:
+   .. code::
+      >> permission_owner("PetriNets", "user2")
 
 .. function:: permission_group(model_name, group)
 
    Change the owning group of the model *model_name* to *group*.
+   The same remarks hold as for all other permission operations.
+
+   Examples:
+
+   To change the owning group of the PetriNets metamodel to group1:
+   .. code::
+      >> permission_group("PetriNets", "group1")
 
 .. function:: group_create(group_name)
 
    Create a new group named *group_name*.
+   You automatically become an administrator for this group.
+
+   Examples:
+
+   To create a new group called group2:
+   .. code::
+      >> group_create("group2")
 
 .. function:: group_delete(group_name)
 
    Delete the group named *group_name*.
+   All users will automatically be kicked from the group, and all permissions previously granted by this group become void.
+
+   Examples:
+
+   To delete the group group2
+   .. code::
+      >> group_delete("group2")
 
 .. function:: group_owner_add(group_name, user_name)
 
    Add user *user_name* as an owner of group *group_name*.
    This automatically makes the user join the specified group if this was not yet the case.
 
+   Examples:
+
+   To add user user1 as a new owner, or group administrator, to group group1:
+   .. code::
+      >> group_owner_add("group1", "user1")
+
 .. function:: group_owner_delete(group_name, user_name)
 
    Remove user *user_name* as an owner of group *group_name*.
 
+   Examples:
+
+   To delete user1 as an owner, or group administrator, from group group1:
+   .. code::
+      >> group_owner_delete("group1", "user1")
+
 .. function:: group_join(group_name, user_name)
 
    Have user *user_name* join the group *group_name* as an ordinary user.
 
+   Examples:
+   
+   To make user user1 join the group group1, of which the current user is an owner:
+   .. code::
+      >> group_join("group1", "user1")
+
 .. function:: group_kick(group_name, user_name)
 
    Remove user *user_name* from the group *group_name*.
    If the user was an owner of the group, these permissions are also revoked.
 
+   Examples:
+
+   To kick user user1 from group group1, of which the current user is an owner:
+   .. code::
+      >> group_kick("group1, "user1")
+
 .. function:: admin_promote(user_name)
 
    Promote user *user_name* to admin status.
-   Admin status grants users access to all operations.
+   Admin status grants users access to all operations, and provides all permission.
+   Effectively, all groups and files have read/write access for the admin user, independent of the stored permissions.
+
+   Examples:
+
+   To promote user1 to admin states:
+   .. code::
+      >> admin_promote("user1")
 
 .. function:: admin_demote(user_name)
 
    Demote user *user_name* to ordinary user.
 
+   Examples:
+
+   To demote user1 to a normal user:
+   .. code::
+      >> admin_demote("user1")
+
 .. function:: element_list(model_name)
 
    Returns a list of all elements and their type specified in the model named *model_name*.
+   This list can contain much more than only simple elements, but includes anonymous edges and attributes as well.
+   It is therefore not recommended for general purpose use; use *element_list_nice* instead.
+
+   Examples:
+
+   To get a list of all elements in the PetriNets metamodel:
+   .. code::
+      >> element_list("PetriNets")
+      [("Place", "Class"),
+       ("Transition", "Class"),
+       ("P2T", "Association"),
+       ("T2P", "Association"),
+       ...]
 
 .. function:: types(model_name)
 
    Returns a list of all types usable in the model named *model_name*.
    This is similar to executing *element_list* on the metamodel of this model.
+   It attempts to filter out most unusable elements.
+
+   Examples:
+
+   To get a list of all types usable in the PetriNets metamodel (i.e., when altering the metamodel itself):
+   .. code..
+      >> types("PetriNets")
+      ["Class", "Association", "SimpleAttribute", ...]
 
 .. function:: types_full(model_name)