-from indexes to volumes, indexed from 1) of volumes. I<$tags> is an
-optional arrayref of tags.
-
-Note that the volumes must be unblessed hashrefs. If I<$vol> is a
-volume, you can use this idiom: C<< $volumes = {1 => {%$vol}} >>.
+from indexes to volume IDs, indexed from 1) of B<extra> volumes (that
+is, volumes other than the root volume). I<$tags> is an optional
+arrayref of tags.
+
+For the I<$volumes> parameter you can pass hashrefs that describe
+volumes instead of volume IDs. This will create new volumes. The
+hashrefs are (presumably) passed to B<create_volume>. An example
+inspired by the official documentation:
+
+ $volumes = { 1 => {
+ name => "vol_demo",
+ organization => "ecc1c86a-eabb-43a7-9c0a-77e371753c0a",
+ size => 10_000_000_000,
+ volume_type => "l_sdd",
+ }};
+
+Note that there B<may not> be any blessed hashrefs inside I<$volumes>.