[PATCH qemu-server 8/8] block job: monitor: properly document function

[Fiona Ebner <f.ebner@proxmox.com>]

Signed-off-by: Fiona Ebner <f.ebner@proxmox.com>
---
 src/PVE/QemuServer/BlockJob.pm | 56 +++++++++++++++++++++++++++++++---
 1 file changed, 51 insertions(+), 5 deletions(-)

diff --git a/src/PVE/QemuServer/BlockJob.pm b/src/PVE/QemuServer/BlockJob.pm
index 5fbc311e..2f4bf3cc 100644
--- a/src/PVE/QemuServer/BlockJob.pm
+++ b/src/PVE/QemuServer/BlockJob.pm
@@ -108,11 +108,57 @@ my sub print_job_status {
     return;
 }
 
-# $completion can be either
-# 'complete': wait until all jobs are ready, job-complete them (default)
-# 'cancel': wait until all jobs are ready, block-job-cancel them
-# 'skip': wait until all jobs are ready, return with block jobs in ready state
-# 'auto': wait until all jobs disappear, only use for jobs which complete automatically
+=head3 monitor
+
+Monitor the given jobs C<$jobs> and handle them according to the mode C<$completion>.
+
+=over
+
+=item C<$qmp_peer>: The QMP peer which is executing the jobs.
+
+=item C<$jobs>: Hash reference with job IDs that should be handled. With optional, additional
+information:
+
+=over
+
+=item C<< $jobs->{$job_id}->{'source-node-name'} >>: (optional, used by mirror) Name of the source
+block node. Will be detached upon completion.
+
+=item C<< $jobs->{$job_id}->{'target-node-name'} >>: (optional, used by mirror) Name of the target
+block node. Will be detached upon cancel.
+
+=back
+
+=item C<$completion>: How to handle the jobs:
+
+=over
+
+=item C<'complete'>: wait until all jobs are ready, job-complete them (default)
+
+=item C<'cancel'>: wait until all jobs are ready, block-job-cancel them
+
+=item C<'skip'>: wait until all jobs are ready, return with block jobs in ready state
+
+=item C<'auto'>: wait until all jobs disappear, only use for jobs which complete automatically
+
+=back
+
+=item C<$operation>: Name of the block job operation.
+
+=item C<$options>: Additional options:
+
+=over
+
+=item C<< $options->{qga} >>: Guest agent string to be considered for guest filesystem freezing.
+
+=item C<< $options->{'dest-vmid'} >>: VM ID of the target of the job.
+
+=back
+
+=back
+
+=cut
+
 sub monitor {
     my ($qmp_peer, $jobs, $completion, $operation, $options) = @_;
 
-- 
2.47.3