virDomainCheckpointCreateXML: Add disclaimer about creating checkpoints

Checkpoints created via virDomainCheckpointCreateXML are generally not
very useful as they need to be coupled with a backup.

Add a disclaimer to the docs explaining why users should use
virDomainBackupBegin instead.

Signed-off-by: Peter Krempa <pkrempa@redhat.com>
Reviewed-by: Jonathon Jongsma <jjongsma@redhat.com>

diff --git a/src/libvirt-domain-checkpoint.c b/src/libvirt-domain-checkpoint.c
index de747aff01d984929753d79547cb2b3f94d2c58c..81107531b6d14bf68578926840485a35efc29811 100644 (file)
--- a/src/libvirt-domain-checkpoint.c
+++ b/src/libvirt-domain-checkpoint.c
@@ -142,6 +142,17 @@ virDomainCheckpointGetConnect(virDomainCheckpointPtr checkpoint)
  * present, an error is thrown. This flag is incompatible with
  * VIR_DOMAIN_CHECKPOINT_CREATE_REDEFINE.
  *
+ * Note: A checkpoint represents point in time after which blocks changed by
+ * the hypervisor are tracked. The tracking of changed blocks notes only whether
+ * a block was modified, but does not preserve the old contents.
+ * The main purpose of checkpoints is to enable incremental backups. But for a
+ * checkpoint to be useful for this purpose, a backup must be performed at the
+ * same time as the checkpoint is created.
+ * This is done via the virDomainBackupBegin API, which also allows to create a
+ * checkpoint at the same time. Creating checkpoints with
+ * virDomainCheckpointCreateXML is generally only useful for re-creating the
+ * libvirt metadata.
+ *
  * Returns an (opaque) new virDomainCheckpointPtr on success or NULL
  * on failure.
  *