Documentation on exceptions

doc/wrappers.rst

@@ -1427,11 +1427,14 @@ For each exception, its superclasses are also indicated after the colon.
 
 .. exception:: UnknownElement : UnknownIdentifier
 
+   The specified model element is unknown in the model.
+
    Examples:
 
-   * 
+   * When instantiating an element of which the type element does not exist.
 
-     >>>
+     >>> instantiate("models/my_pn", "CapacityConstrainedPlace")
+     UnknownElement()
 
 .. exception:: UnknownModel : UnknownIdentifier
 
@@ -1447,27 +1450,37 @@ For each exception, its superclasses are also indicated after the colon.
 
 .. exception:: UnknownLocation : UnknownIdentifier
 
+   The specified location could not be resolved, indicating that no element exists at that location.
+   Note that there is no information as to the level at which the resolution goes wrong (e.g., a parent folder might already not exist).
+
    Examples:
 
-   * 
+   * When reading out the permissions of a non-existing location.
 
-     >>>
+     >>> read_permissions("a/b/c/d/e/f/g")
+     UnknownLocation()
 
 .. exception:: UnknownGroup : UnknownIdentifier
 
+   The specified group does not exist.
+
    Examples:
 
-   * 
+   * When deleting a group that doesn't exist.
 
-     >>>
+     >>> group_delete("no_such_group")
+     UnknownGroup()
 
 .. exception:: UnknownUser : UnknownIdentifier
 
+   The specified user does not exist.
+
    Examples:
 
-   * 
+   * When making a (non-existing) user join a group.
 
-     >>>
+     >>> group_join("existing_group", "non_existing_user")
+     UnknownUser()
 
 .. exception:: ConnectionError : ModelverseException
 
@@ -1485,27 +1498,30 @@ For each exception, its superclasses are also indicated after the colon.
 
 .. exception:: ExistsError : ModelverseException
 
-   Examples:
-
-   * 
-
-     >>>
+   Abstract exception that indicates that a requested element to be created already exists.
+   Never occurs on its own.
 
 .. exception:: AttributeExists : ExistsError
 
+   A to-be-created attribute already exists, and could therefore not be created (or renamed to this).
+
    Examples:
 
-   * 
+   * Renaming an attribute to one that already exists.
 
-     >>>
+     >>> attribute_name("formalisms/PetriNets", "Place", "tokens", "name")
+     AttributeExists()
 
 .. exception:: ElementExists : ExistsError
 
-   Examples:
+   A to-be-created element already exists, and could therefore not be created.
 
-   * 
+   Examples:
 
-     >>>
+   * Instantiating another element with ID Place, which already exists.
+   
+     >>> instantiate("formalisms/PetriNets", "Class", ID="Place")
+     ElementExists()
 
 .. exception:: ModelExists : ExistsError
 
@@ -1522,35 +1538,41 @@ For each exception, its superclasses are also indicated after the colon.
 
 .. exception:: FolderExists : ExistsError
 
+   The folder you want to create already exists.
+
    Examples:
 
-   * 
+   * When creating a folder that already exists.
 
-     >>>
+     >>> folder_create("formalisms")
+     FolderExists()
 
 .. exception:: GroupExists : ExistsError
 
+   The group already exists.
+
    Examples:
 
-   * 
+   * When creating a new group that already exists.
 
-     >>>
+     >>> group_create("users")
+     GroupExists()
 
 .. exception:: UserExists : ExistsError
 
+   The user already exists or is already a member of the group.
+
    Examples:
 
-   * 
+   * When adding a user to a group, while the user is already in there.
 
-     >>>
+     >>> group_join("users", "user")
+     UserExists()
 
 .. exception:: PermissionDenied : ModelverseException
 
-   Examples:
-
-   * 
-
-     >>>
+   Permission denied to a specific artefact.
+   This is an abstract exception that is further subclassed by other exceptions.
 
 .. exception:: ReadPermissionDenied : PermissionDenied