docs: improve documentation for copy directives

As of now it is unclear how copy directives are supposed to work.
This commit improves the description, although there are still many
under-specified aspects to be addressed later on.

Signed-off-by: Silvano Cirujano Cuesta <[email protected]>

src/linkml_map/datamodel/transformer_model.yaml

@@ -340,18 +340,45 @@ classes:
   CopyDirective:
     description: >-
       Instructs a Schema Mapper in how to map to a target schema. Not used for data transformation.
+
+      This is the process to process a directive:
+      1. If `copy_all`, add all sub-elements to the list of sub-elements to be copied.
+      2. If `exclude`, remove the specified sub-elements from the above list.
+      3. If `exclude_all`, clean-up the above list. Effectively making previous steps useless.
+      4. If `include`, add the specified sub-elements from the list result of previous steps.
+
+      Implementations might decide to somehow report (error, warning,...) meaningless combinations (like specifying `copy_all` and `exclude_all`). 
+
+      Validation on the correctness of the resulting derived schema might be done optionally by the implementation.
+      For example, removing a slot but keeping a class that requires it would invalidate the derived-schema.
+      It is always possible to validate the schema with the LinkML linter after derivation.
+
+      What are the considered sub-elements depends on the calls of Element to be transformed.
+      For example, for a class they are `slots` and `attributes`.
     status: testing
     attributes:
       element_name:
         key: true
       copy_all:
         range: boolean
+        description: Copy all sub-elements of the Element being derived.
       exclude_all:
         range: boolean
+        description: Do not copy any of the sub-elements of the Element being derived.
       exclude:
         range: Any
+        description: >-
+          Remove certain sub-elements from the list of sub-elements to be copied.
+
+          As of now there it is under-specified, how to specify the sub-elements to exclude.
+          One possible implementation would be a list where all element types can be mixed, since there might not be name conflicts across element types.
       include:
         range: Any
+        description: >-
+          Add certain sub-elements to the list of sub-elements to be copied.
+
+          As of now there it is under-specified, how to specify the sub-elements to include.
+          One possible implementation would be a list where all element types can be mixed, since there might not be name conflicts across element types.
       add:
         range: Any
 
@@ -366,4 +393,4 @@ enums:
     permissible_values:
       JSON:
       YAML:
-      TURTLE:
+      TURTLE: