Add some more documentation

doc/wrappers.rst

@@ -795,24 +795,131 @@ Functions
 
 .. function:: service_register(name, function)
 
+   Registers the current client-side thread as a service in the Modelverse.
+   The specified *function* will be executed when users make a request to the service specified by *name*.
+   This function will be executed on a different thread for each incoming request for a new instance of the service.
+   If required, synchronization must be built in manually.
+   After making this call, the thread should stay alive, but can do whatever other operation is required.
+   Note that, upon termination, this client **MUST** call the *service_stop()* function, as otherwise the Modelverse is not notified of this service deregistering.
+
+   The service is initially invoked with a Modelverse port to use for communication.
+   This port must be used in all requests made to the Modelverse in the context of this service.
+   The only two supported operations now are *service_set* (send data to the Modelverse) and *service_get* (fetch data from the Modelverse).
+
+   Examples:
+
+   To register a Fibonacci service:
+   .. code::
+      >> def fibonacci_service(port):
+      >>     def fibonacci(value):
+      >>         if value <= 2:
+      >>             return 1
+      >>         else:
+      >>             return fibonacci(value-1) + fibonacci(value-2)
+      >>     service_set(port, fibonacci, service_get(port))
+      >> service_register("fibonacci", fibonacci_service)
+
 .. function:: service_stop()
 
+   Stops the current service from being available to the Modelverse.
+   Existing connections will not be forcibly terminated, and these run on separate threads.
+
+   Example:
+
+   To stop the currently executing service:
+   .. code::
+      >> service_stop()
+
 .. function:: service_get(port)
 
+   When running a serivce, it is often necessary to request data from the Modelverse.
+   This data can be sent whatever way in the Modelverse.
+   Different Modelverse executions are identified by their differing *port*, which is received upon the client invoking the external service.
+   Note that this call is blocking.
+   That is, only when data is available, will this function return.
+
+   Example:
+
+   To get data from a currently executing Modelverse client:
+   .. code::
+      >> service_get(port)
+      5
+
 .. function:: service_set(port, value)
 
+   When running a service, it is often necessary to send data back to the Modelverse.
+   This can be either for conversing with the user (e.g., prompting), or for sending the result back.
+   Any primitive value can be sent to the Modelverse as a value.
+
+   Example:
+
+   To send the result back to the Modelverse:
+   .. code::
+      >> service_set(port, 5)
+
 .. function:: user_password(user, password)
 
+   Changes the password of user *user* to *password*.
+   Permissions on this operation are of course rather strict:
+   users can only modify their own password.
+   Of course, an administrator can modify the password of every user.
+
+   Example:
+
+   To change the password of user *user1* to *my_password*:
+   .. code::
+      >> user_password("user1", "my_password")
+
 .. function:: transformation_read_signature(transformation)
 
+   Returns the signature of the transformation *transformation*.
+   The signature consists of two dictionaries: the first specifies the input signature, and the second one specifies the output signature.
+   Both dictionaries have the same structure: the keys represent the names of the model while invoking the operation, and the values represent the expected type of the model.
+
+   Example:
+
+   To read out the signature of the "plant_refine" operation:
+   >> transformation_read_signature("plant_refine")
+   ({"req": "Requirements", "plant": "Plant"}, {"plant": "Plant"})
+
 .. function:: element_list_nice(model_name)
 
+   Returns a complete representation of a model in a compact dicationary-like representation.
+   This is basically a list of dictionaries, each dictionary containing the values usually obtained with *read_attrs*.
+   Additionally, some special keys are added: *id* (the identifier returned upon instantiation), *__source* (the source of the association, if it was an association), and *__target* (the target of the association, if it was an association).
+
+   Example:
+
+   To read out a list of a PetriNets instance model:
+   .. code::
+      >> element_list_nice("my_pn")
+      [{"id": "p1", "name": "a place", "tokens": 1},
+       {"id": "t1", "name": "a transition"},
+       {"id": "p1_to_t1", "name": "transition", "__source": "p1", "__target": "t1", "weight": 1}]
+
 .. function:: connections_between(model_name, source_element, target_element)
 
+   Returns a list of all allowed connection types between *source_element* and *target_element* in a specified model.
+   Both elements need to be part of the same model, as otherwise a merged model should be created beforehand.
+
+   Example:
+
+   To read out the allowed connections between elements "p1" and "t1":
+   .. code::
+      >> connections_between("my_pn", "p1", "t1")
+      ["P2T"]
+
+   To read out the allowed connections from the Place class to itself:
+   .. code::
+      >> connections_between("PetriNets", "Place", "Place")
+      ["Association", "Inheritance"]
+
 .. function:: define_attribute(model_name, node, attr_name, attr_type)
 
 .. function:: all_instances(model_name, type_name)
 
+.. function:: service_poll(port)
+
 Exceptions
 ^^^^^^^^^^