checkpoint: Mention that VIR_DOMAIN_CHECKPOINT_XML_SIZE is expensive and stale

Data is valid only when queried as guest writes may increase the backup
size.

Signed-off-by: Peter Krempa <pkrempa@redhat.com>
Reviewed-by: Eric Blake <eblake@redhat.com>

docs/formatcheckpoint.rst

@@ -86,6 +86,10 @@ The top-level ``domaincheckpoint`` element may contain the following elements:
          perform a dynamic query of the estimated size in bytes of the changes
          made since the checkpoint was created.
 
+         Note that updating the backup ``size`` may be expensive and
+         the actual required size may increase if the guest OS is actively
+         writing to the disk.
+
 ``creationTime``
    A readonly representation of the time this checkpoint was created. The time
    is specified in seconds since the Epoch, UTC (i.e. Unix time).

src/libvirt-domain-checkpoint.c

@@ -191,7 +191,8 @@ virDomainCheckpointCreateXML(virDomainPtr domain,
  * VIR_DOMAIN_CHECKPOINT_XML_SIZE, each <disk> listing adds an additional
  * attribute that shows an estimate of the current size in bytes that
  * have been dirtied between the time the checkpoint was created and the
- * current point in time.
+ * current point in time. Note that updating the size may be expensive and
+ * data will be inaccurate once guest OS writes to the disk.
  *
  * Returns a 0 terminated UTF-8 encoded XML instance or NULL in case
  * of error. The caller must free() the returned value.