[PATCH 3/4] virDomainCheckpointCreateXML: Add disclaimer about creating checkpoints

[Peter Krempa]

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 at redhat.com>
---
 src/libvirt-domain-checkpoint.c | 10 ++++++++++
 1 file changed, 10 insertions(+)

diff --git a/src/libvirt-domain-checkpoint.c b/src/libvirt-domain-checkpoint.c
index de747aff01..078e999bf3 100644
--- a/src/libvirt-domain-checkpoint.c
+++ b/src/libvirt-domain-checkpoint.c
@@ -142,6 +142,16 @@ virDomainCheckpointGetConnect(virDomainCheckpointPtr checkpoint)
  * present, an error is thrown. This flag is incompatible with
  * VIR_DOMAIN_CHECKPOINT_CREATE_REDEFINE.
  *
+ * Note: A checkpoint represent s point in time since 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. This means that
+ * for a checkpoint to be generally usable for doing an incremental backup it's
+ * required to perform a backup at the same time as taking the checkpoint.
+ * This is done via the virDomainBackupBegin API, which also allows to create
+ * a checkpoint at the same time. virDomainCheckpointCreateXML is generally not
+ * useful for creating checkpoints but rather only for re-creating the libvirt
+ * metadata.
+ *
  * Returns an (opaque) new virDomainCheckpointPtr on success or NULL
  * on failure.
  *
-- 
2.37.1