More documentation

doc/wrappers.rst

@@ -141,19 +141,27 @@ Functions
 
 .. function:: transformation_execute_MANUAL(operation_name, input_models_dict, output_models_dict, callback=lambda i: None)
 
-   Expl
+   Executes the manual model operation *operation_name*.
+   Furthermore, this is identical to *transformation_execute_AL*, with the exception of the *callback* function.
+   In this case, the callback function can be just another series of Modelverse operations, though pertaining to a single model.
+   As such, the *model_name* parameter of these operations **MUST** be set to *None*.
 
 .. function:: transformation_execute_MT(operation_name, input_models_dict, output_models_dict, callback=lambda i: None)
 
-   Expl
+   Executes the model transformation operation *operation_name*.
+   Identical to *transformation_execute_AL*.
 
 .. function:: transformation_list()
 
-   Expl
+   Returns a list of all operations specified in the Modelverse, together with their type.
 
 .. function:: process_execute(process_name, prefix, callbacks)
 
-   Expl
+   Execute the process model stored as *process_name*.
+   All models are stored with their names prefixed with *prefix* to allow for multiple executions of the same model.
+   Note that this applies to the resolution of input models as well.
+   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.
 
 .. function:: permission_modify()
 
@@ -201,118 +209,141 @@ Functions
 
 .. function:: element_list(model_name)
 
-   Expl
+   Returns a list of all elements and their type specified in the model named *model_name*.
 
 .. function:: types(model_name)
 
-   Expl
+   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.
 
 .. function:: types_full(model_name)
 
-   Expl
+   Returns a list of all types usable in the model named *model_name*.
+   In contrast to *types*, this includes hidden elements as well (i.e., those starting with __)
 
 .. function:: read(model_name, ID)
 
-   Expl
+   Read the content of model element *ID* in model *model_name*.
+   This returns the type of the element, and the set of source and destination if the element is an edge (*None* otherwise).
 
 .. function:: read_attrs(model_name, ID)
 
-   Expl
+   Return a dictionary of all attributes of model element *ID* in model *model_name*, containing their values.
+   All values in the Modelverse are primitive types, and as such, this is also the case in this operation.
 
 .. function:: instantiate(model_name, typename, edge=None, ID="")
 
-   Expl
+   Instantiate a new instance of *typename* in the model *model_name*.
+   If the instance is an edge, provide a tuple containing the source and target as *edge*.
+   A preferred *ID* can be specified, though there is no guarantee that this name is actually taken (e.g., if it is already taken by another element).
+   This operation returns the actually assigned ID.
 
 .. function:: delete_element(model_name, ID)
 
-   Expl
+   Delete the element *ID* in the model *model_name*.
+   This is a recursive delete, and all incoming and outgoing edges will be removed (recursively) as well.
 
 .. function:: attr_assign(model_name, ID, attr, value)
 
-   Expl
+   Assign the value *value* to the attribute named *attr* of the element *ID* in the model named *model_name*.
+   If the attribute already has an assigned value, the previous value is removed first.
 
 .. function:: attr_assign_code(model_name, ID, attr, code)
 
-   Expl
+   Assign the code block *code* to the attribute named *attr* of the element *ID* in the model named *model_name*.
+   If the attribute already has an assigned value, the previous value is removed first.
+   The assigned code is compiled to Action Language by the HUTN compiler.
 
 .. function:: attr_delete(model_name, ID, attr)
 
-   Expl
+   Unset the attribute *attr* of model element *ID* in the model *model_name*.
 
 .. function:: read_outgoing(model_name, ID, typename)
 
-   Expl
+   Returns a list of all outgoing associations of *ID*, typed by *typename*, in model *model_name*.
+   Typename can be set to the empty string to indicate that all types must match.
+   Note that this returns the association itself, **NOT** the destination.
 
 .. function:: read_incoming(model_name, ID, typename)
 
-   Expl
+   Returns a list of all incoming associations of *ID*, typed by *typename*, in model *model_name*.
+   Typename can be set to the empty string to indicate that all types must match.
+   Note that this returns the association itself, **NOT** the source.
 
 .. function:: read_association_source(model_name, ID)
 
-   Expl
+   Returns the identifier of the source of association *ID* in model *model_name*.
 
 .. function:: read_association_destination(model_name, ID)
 
-   Expl
+   Returns the identifier of the target of association *ID* in model *model_name*.
 
 Exceptions
 ^^^^^^^^^^
 
+Below is a list of all exceptions that the wrappers can raise, together with a summary of the kind of error that occured.
+
 .. exception:: ModelverseException
 
-   Expl
+   Generic Modelverse Exception, of which all others inherit.
+   This should be the only type of exception that the wrapper can raise.
 
 .. exception:: UnknownError
 
-   Expl
+   Unknown exception has occured.
+   This is likely something wrong with the connection, such as the Modelverse that suddenly disconnected.
 
 .. exception:: UnknownIdentifier
 
-   Expl
+   The specified identifier could not be resolved in the Modelverse.
 
 .. exception:: UnknownType
 
-   Expl
+   The specified identifier could not be resolved as a type in the Modelverse.
 
 .. exception:: NotAnAssociation
 
-   Expl
+   The specified identifier does not resolve to an association (or edge), even though this was intended.
 
 .. exception:: UnsupportedValue
 
-   Expl
+   The specified value is not a primitive that can be serialized.
+   Supported types are: string, boolean, integer, float, and action.
 
 .. exception:: CompilationError
 
-   Expl
+   Error in the HUTN compiler during compilation.
 
 .. exception:: NoSuchAttribute
 
-   Expl
+   The specified attribute does not exist for this element.
 
 .. exception:: UnknownModel
 
-   Expl
+   The specified model can not be resolved in the Modelverse.
 
 .. exception:: ConnectionError
 
-   Expl
+   Error with the connection to the Modelverse.
 
 .. exception:: ModelExists
 
-   Expl
+   The identifier to give to the newly created model already exists.
 
 .. exception:: PermissionDenied
 
-   Expl
+   Permission denied to either write or read the specified resource.
 
 .. exception:: InvalidMode
 
-   Expl
+   An operation was executed in the wrong context.
+   For example, all operations are only valid after a successful *init* and *login* call.
 
 .. exception:: InterfaceMismatch
 
-   Expl
+   The Modelverse responded with an unexpected response.
+   As a response came, the Modelverse is likely still running, though we have no idea how to interpret the result.
+   Likely, the wrapper is not up to date with the latest Modelverse operations.
 
 Custom
 ------