Update the docs for Volume.compose

* Give the parameters meaningful names * Describe host this might be implemented with delta files * Declare that the parent volume should be considered invalid after completion. Signed-off-by: Mark Syms <[email protected]>
xapi-project · Sep 4, 2024 · d9534cf · d9534cf
1 parent 59664cc
commit d9534cf
Showing 1 changed file with 9 additions and 3 deletions.
diff --git a/ocaml/xapi-storage/generator/lib/control.ml b/ocaml/xapi-storage/generator/lib/control.ml
@@ -421,9 +421,15 @@ module Volume (R : RPC) = struct
   let compose =
     R.declare "compose"
       [
-        "[compose sr volume1 volume2] layers the updates from [volume2] onto"
-      ; "[volume1], modifying [volume2]. Implementations shall declare the"
-      ; "VDI_COMPOSE feature for this method to be supported."
+        "[compose sr child_volume parent_volume] layers the updates from "
+      ; "[child_volume] onto [parent_volume], modifying [child_volume]. "
+      ; "In the case of a delta file format this means updating the "
+      ; "[child_volume] to have a parent or backing object defined by "
+      ; "[parent_volume]. Implementations shall declare the VDI_COMPOSE "
+      ; "feature for this method to be supported. After a successful "
+      ; "return it should be assumed that the [parent_volume] is no "
+      ; "longer valid. Calling SR.ls, will return the list of currently "
+      ; "known, valid, volumes."
       ]
       (dbg @-> sr @-> key @-> key2 @-> returning unit errors)