snapshot: Various doc tweaks

Since I was copying this text to form checkpoint XML and API
documentation, I might as well make improvements along the way. Most
of these changes are based on reviews of the checkpoint docs.

Among other things: grammar tweaks, point to a single source of
documentation rather than repeating verbosity, reword things for
easier legibility.

Signed-off-by: Eric Blake <eblake@redhat.com>
Reviewed-by: Daniel P. Berrangé <berrange@redhat.com>

2 files changed, 89 insertions, 213 deletions

diff --git a/docs/formatsnapshot.html.in b/docs/formatsnapshot.html.in
index 146908ce76..1bbbf06205 100644
--- a/docs/formatsnapshot.html.in
+++ b/docs/formatsnapshot.html.in
@@ -99,16 +99,14 @@
     </p>
     <dl>
       <dt><code>name</code></dt>
-      <dd>The name for this snapshot.  If the name is specified when
-        initially creating the snapshot, then the snapshot will have
-        that particular name.  If the name is omitted when initially
-        creating the snapshot, then libvirt will make up a name for
-        the snapshot, based on the time when it was created.
+      <dd>The optional name for this snapshot.  If the name is
+        omitted, libvirt will create a name based on the time of the
+        creation.
       </dd>
       <dt><code>description</code></dt>
-      <dd>A human-readable description of the snapshot.  If the
-        description is omitted when initially creating the snapshot,
-        then this field will be empty.
+      <dd>An optional human-readable description of the snapshot.  If
+        the description is omitted when initially creating the
+        snapshot, then this field will be empty.
       </dd>
       <dt><code>memory</code></dt>
       <dd>On input, this is an optional request for how to handle VM
@@ -200,46 +198,52 @@
         </dl>
       </dd>
       <dt><code>creationTime</code></dt>
-      <dd>The time this snapshot was created.  The time is specified
-        in seconds since the Epoch, UTC (i.e. Unix time).  Readonly.
+      <dd>A readonly representation of the time this snapshot was
+        created.  The time is specified in seconds since the Epoch,
+        UTC (i.e. Unix time).
       </dd>
       <dt><code>state</code></dt>
-      <dd>The state of the domain at the time this snapshot was taken.
-        If a full system snapshot was created, then this
-        is the state of the domain at that time. When the domain is
-        reverted to this snapshot, the domain's state will default to
-        this state, unless overridden
+      <dd>A readonly representation of the state of the domain at the
+        time this snapshot was taken.  If a full system snapshot was
+        created, then this is the state of the domain at that
+        time. When the domain is reverted to this snapshot, the
+        domain's state will default to this state, unless overridden
         by <code>virDomainRevertToSnapshot()</code> flags to revert to
-        a running or paused state. Additionally,
-        this field can be the value "disk-snapshot"
-        (<span class="since">since 0.9.5</span>) when it represents
-        only a disk snapshot (no VM memory state), and reverting to this
-        snapshot will default to an inactive guest.  Readonly.
+        a running or paused state. Additionally, this field can be the
+        value "disk-snapshot" (<span class="since">since 0.9.5</span>)
+        when it represents only a disk snapshot (no VM memory state),
+        and reverting to this snapshot will default to an inactive
+        guest.
       </dd>
       <dt><code>parent</code></dt>
-      <dd>The parent of this snapshot.  If present, this element
-        contains exactly one child element, name.  This specifies the
-        name of the parent snapshot of this snapshot, and is used to
-        represent trees of snapshots.  Readonly.
+      <dd>An optional readonly representation of the parent of this
+        snapshot.  If present, this element contains exactly one child
+        element, <code>name</code>.  This specifies the name of the
+        parent snapshot of this snapshot, and is used to represent
+        trees of snapshots.
       </dd>
       <dt><code>domain</code></dt>
-      <dd>The domain that this snapshot was taken against.  Older
-        versions of libvirt stored only a single child element, uuid;
-        reverting to a snapshot like this is risky if the current
-        state of the domain differs from the state that the domain was
-        created in, and requires the use of the
-        <code>VIR_DOMAIN_SNAPSHOT_REVERT_FORCE</code> flag
+      <dd>A readonly representation of the domain that this snapshot
+        was taken against.  Older versions of libvirt stored only a
+        single child element, uuid; reverting to a snapshot like this
+        is risky if the current state of the domain differs from the
+        state that the domain was created in, and requires the use of
+        the <code>VIR_DOMAIN_SNAPSHOT_REVERT_FORCE</code> flag
         in <code>virDomainRevertToSnapshot()</code>.  Newer versions
-        of libvirt (<span class="since">since 0.9.5</span>) store the entire
-        inactive <a href="formatdomain.html">domain configuration</a>
-        at the time of the snapshot (<span class="since">since
-        0.9.5</span>).  Readonly.
+        of libvirt (<span class="since">since 0.9.5</span>) store the
+        entire inactive <a href="formatdomain.html">domain
+        configuration</a> at the time of the snapshot
+        (<span class="since">since 0.9.5</span>). The domain will have
+        security-sensitive information omitted
+        unless the flag <code>VIR_DOMAIN_SNAPSHOT_XML_SECURE</code> is
+        provided on a read-write connection.
       </dd>
       <dt><code>cookie</code></dt>
-      <dd>Save image cookie containing additional data libvirt may need to
-        properly restore a domain from an active snapshot when such data
-        cannot be stored directly in the <code>domain</code> to maintain
-        compatibility with older libvirt or hypervisor. Readonly.
+      <dd>An optional readonly representation of a save image cookie
+        containing additional data libvirt may need to properly
+        restore a domain from an active snapshot when such data cannot
+        be stored directly in the <code>domain</code> to maintain
+        compatibility with older libvirt or hypervisor.
       </dd>
     </dl>
 
diff --git a/src/libvirt-domain-snapshot.c b/src/libvirt-domain-snapshot.c
index be9bf71af9..0c8023d9f6 100644
--- a/src/libvirt-domain-snapshot.c
+++ b/src/libvirt-domain-snapshot.c
@@ -142,8 +142,10 @@ virDomainSnapshotGetConnect(virDomainSnapshotPtr snapshot)
  * support these flags.
  *
  * If @flags includes VIR_DOMAIN_SNAPSHOT_CREATE_NO_METADATA, then the
- * domain's disk images are modified according to @xmlDesc, but then
- * the just-created snapshot has its metadata deleted.  This flag is
+ * domain's disk images are modified according to @xmlDesc, but
+ * libvirt does not track any metadata (similar to immediately calling
+ * virDomainSnapshotDelete() with
+ * VIR_DOMAIN_SNAPSHOT_DELETE_METADATA_ONLY).  This flag is
  * incompatible with VIR_DOMAIN_SNAPSHOT_CREATE_REDEFINE.
  *
  * If @flags includes VIR_DOMAIN_SNAPSHOT_CREATE_HALT, then the domain
@@ -203,7 +205,8 @@ virDomainSnapshotGetConnect(virDomainSnapshotPtr snapshot)
  * virDomainSnapshotFree should be used to free the resources after the
  * snapshot object is no longer needed.
  *
- * Returns an (opaque) virDomainSnapshotPtr on success, NULL on failure.
+ * Returns an (opaque) new virDomainSnapshotPtr on success or NULL on
+ * failure.
  */
 virDomainSnapshotPtr
 virDomainSnapshotCreateXML(virDomainPtr domain,
@@ -260,7 +263,7 @@ virDomainSnapshotCreateXML(virDomainPtr domain,
  * VIR_DOMAIN_SNAPSHOT_XML_SECURE; this flag is rejected on read-only
  * connections.
  *
- * Returns a 0 terminated UTF-8 encoded XML instance, or NULL in case
+ * Returns a 0 terminated UTF-8 encoded XML instance or NULL in case
  * of error. The caller must free() the returned value.
  */
 char *
@@ -308,37 +311,11 @@ virDomainSnapshotGetXMLDesc(virDomainSnapshotPtr snapshot,
  * @flags only if virDomainSnapshotListNames() can honor it, although
  * the flag has no other effect here.
  *
- * By default, this command covers all snapshots; it is also possible to
- * limit things to just snapshots with no parents, when @flags includes
- * VIR_DOMAIN_SNAPSHOT_LIST_ROOTS.  Additional filters are provided in
- * groups, where each group contains bits that describe mutually exclusive
- * attributes of a snapshot, and where all bits within a group describe
- * all possible snapshots.  Some hypervisors might reject explicit bits
- * from a group where the hypervisor cannot make a distinction.  For a
- * group supported by a given hypervisor, the behavior when no bits of a
- * group are set is identical to the behavior when all bits in that group
- * are set.  When setting bits from more than one group, it is possible to
- * select an impossible combination, in that case a hypervisor may return
- * either 0 or an error.
- *
- * The first group of @flags is VIR_DOMAIN_SNAPSHOT_LIST_LEAVES and
- * VIR_DOMAIN_SNAPSHOT_LIST_NO_LEAVES, to filter based on snapshots that
- * have no further children (a leaf snapshot).
- *
- * The next group of @flags is VIR_DOMAIN_SNAPSHOT_LIST_METADATA and
- * VIR_DOMAIN_SNAPSHOT_LIST_NO_METADATA, for filtering snapshots based on
- * whether they have metadata that would prevent the removal of the last
- * reference to a domain.
- *
- * The next group of @flags is VIR_DOMAIN_SNAPSHOT_LIST_INACTIVE,
- * VIR_DOMAIN_SNAPSHOT_LIST_ACTIVE, and VIR_DOMAIN_SNAPSHOT_LIST_DISK_ONLY,
- * for filtering snapshots based on what domain state is tracked by the
- * snapshot.
- *
- * The next group of @flags is VIR_DOMAIN_SNAPSHOT_LIST_INTERNAL and
- * VIR_DOMAIN_SNAPSHOT_LIST_EXTERNAL, for filtering snapshots based on
- * whether the snapshot is stored inside the disk images or as
- * additional files.
+ * By default, this command covers all snapshots. It is also possible
+ * to limit things to just snapshots with no parents, when @flags
+ * includes VIR_DOMAIN_SNAPSHOT_LIST_ROOTS.  Additional filters are
+ * provided via the same @flags values as documented in
+ * virDomainListAllSnapshots().
  *
  * Returns the number of domain snapshots found or -1 in case of error.
  */
@@ -386,37 +363,11 @@ virDomainSnapshotNum(virDomainPtr domain, unsigned int flags)
  * starting from that earlier snapshot; otherwise, the order of
  * snapshots in the resulting list is unspecified.
  *
- * By default, this command covers all snapshots; it is also possible to
- * limit things to just snapshots with no parents, when @flags includes
- * VIR_DOMAIN_SNAPSHOT_LIST_ROOTS.  Additional filters are provided in
- * groups, where each group contains bits that describe mutually exclusive
- * attributes of a snapshot, and where all bits within a group describe
- * all possible snapshots.  Some hypervisors might reject explicit bits
- * from a group where the hypervisor cannot make a distinction.  For a
- * group supported by a given hypervisor, the behavior when no bits of a
- * group are set is identical to the behavior when all bits in that group
- * are set.  When setting bits from more than one group, it is possible to
- * select an impossible combination, in that case a hypervisor may return
- * either 0 or an error.
- *
- * The first group of @flags is VIR_DOMAIN_SNAPSHOT_LIST_LEAVES and
- * VIR_DOMAIN_SNAPSHOT_LIST_NO_LEAVES, to filter based on snapshots that
- * have no further children (a leaf snapshot).
- *
- * The next group of @flags is VIR_DOMAIN_SNAPSHOT_LIST_METADATA and
- * VIR_DOMAIN_SNAPSHOT_LIST_NO_METADATA, for filtering snapshots based on
- * whether they have metadata that would prevent the removal of the last
- * reference to a domain.
- *
- * The next group of @flags is VIR_DOMAIN_SNAPSHOT_LIST_INACTIVE,
- * VIR_DOMAIN_SNAPSHOT_LIST_ACTIVE, and VIR_DOMAIN_SNAPSHOT_LIST_DISK_ONLY,
- * for filtering snapshots based on what domain state is tracked by the
- * snapshot.
- *
- * The next group of @flags is VIR_DOMAIN_SNAPSHOT_LIST_INTERNAL and
- * VIR_DOMAIN_SNAPSHOT_LIST_EXTERNAL, for filtering snapshots based on
- * whether the snapshot is stored inside the disk images or as
- * additional files.
+ * By default, this command covers all snapshots. It is also possible
+ * to limit things to just snapshots with no parents, when @flags
+ * includes VIR_DOMAIN_SNAPSHOT_LIST_ROOTS.  Additional filters are
+ * provided via the same @flags values as documented in
+ * virDomainListAllSnapshots().
  *
  * Note that this command is inherently racy: another connection can
  * define a new snapshot between a call to virDomainSnapshotNum() and
@@ -465,12 +416,12 @@ virDomainSnapshotListNames(virDomainPtr domain, char **names, int nameslen,
 /**
  * virDomainListAllSnapshots:
  * @domain: a domain object
- * @snaps: pointer to variable to store the array containing snapshot objects,
+ * @snaps: pointer to variable to store the array containing snapshot objects
  *         or NULL if the list is not required (just returns number of
  *         snapshots)
  * @flags: bitwise-OR of supported virDomainSnapshotListFlags
  *
- * Collect the list of domain snapshots for the given domain, and allocate
+ * Collect the list of domain snapshots for the given domain and allocate
  * an array to store those objects.  This API solves the race inherent in
  * virDomainSnapshotListNames().
  *
@@ -482,18 +433,15 @@ virDomainSnapshotListNames(virDomainPtr domain, char **names, int nameslen,
  * otherwise, the order of snapshots in the resulting list is
  * unspecified.
  *
- * By default, this command covers all snapshots; it is also possible to
- * limit things to just snapshots with no parents, when @flags includes
- * VIR_DOMAIN_SNAPSHOT_LIST_ROOTS.  Additional filters are provided in
- * groups, where each group contains bits that describe mutually exclusive
- * attributes of a snapshot, and where all bits within a group describe
- * all possible snapshots.  Some hypervisors might reject explicit bits
- * from a group where the hypervisor cannot make a distinction.  For a
- * group supported by a given hypervisor, the behavior when no bits of a
- * group are set is identical to the behavior when all bits in that group
- * are set.  When setting bits from more than one group, it is possible to
- * select an impossible combination, in that case a hypervisor may return
- * either 0 or an error.
+ * By default, this command covers all snapshots. It is also possible
+ * to limit things to just snapshots with no parents, when @flags
+ * includes VIR_DOMAIN_SNAPSHOT_LIST_ROOTS.  Additional filters are
+ * provided in groups listed below. Within a group, bits are mutually
+ * exclusive, where all possible snapshots are described by exactly
+ * one bit from the group. Some hypervisors might reject particular
+ * flags where it cannot make a distinction for filtering. If the set
+ * of filter flags selected forms an impossible combination, the
+ * hypervisor may return either 0 or an error.
  *
  * The first group of @flags is VIR_DOMAIN_SNAPSHOT_LIST_LEAVES and
  * VIR_DOMAIN_SNAPSHOT_LIST_NO_LEAVES, to filter based on snapshots that
@@ -562,37 +510,11 @@ virDomainListAllSnapshots(virDomainPtr domain, virDomainSnapshotPtr **snaps,
  * @flags only if virDomainSnapshotListChildrenNames() can honor it,
  * although the flag has no other effect here.
  *
- * By default, this command covers only direct children; it is also possible
- * to expand things to cover all descendants, when @flags includes
- * VIR_DOMAIN_SNAPSHOT_LIST_DESCENDANTS.  Also, some filters are provided in
- * groups, where each group contains bits that describe mutually exclusive
- * attributes of a snapshot, and where all bits within a group describe
- * all possible snapshots.  Some hypervisors might reject explicit bits
- * from a group where the hypervisor cannot make a distinction.  For a
- * group supported by a given hypervisor, the behavior when no bits of a
- * group are set is identical to the behavior when all bits in that group
- * are set.  When setting bits from more than one group, it is possible to
- * select an impossible combination, in that case a hypervisor may return
- * either 0 or an error.
- *
- * The first group of @flags is VIR_DOMAIN_SNAPSHOT_LIST_LEAVES and
- * VIR_DOMAIN_SNAPSHOT_LIST_NO_LEAVES, to filter based on snapshots that
- * have no further children (a leaf snapshot).
- *
- * The next group of @flags is VIR_DOMAIN_SNAPSHOT_LIST_METADATA and
- * VIR_DOMAIN_SNAPSHOT_LIST_NO_METADATA, for filtering snapshots based on
- * whether they have metadata that would prevent the removal of the last
- * reference to a domain.
- *
- * The next group of @flags is VIR_DOMAIN_SNAPSHOT_LIST_INACTIVE,
- * VIR_DOMAIN_SNAPSHOT_LIST_ACTIVE, and VIR_DOMAIN_SNAPSHOT_LIST_DISK_ONLY,
- * for filtering snapshots based on what domain state is tracked by the
- * snapshot.
- *
- * The next group of @flags is VIR_DOMAIN_SNAPSHOT_LIST_INTERNAL and
- * VIR_DOMAIN_SNAPSHOT_LIST_EXTERNAL, for filtering snapshots based on
- * whether the snapshot is stored inside the disk images or as
- * additional files.
+ * By default, this command covers only direct children. It is also
+ * possible to expand things to cover all descendants, when @flags
+ * includes VIR_DOMAIN_SNAPSHOT_LIST_DESCENDANTS. Additional filters
+ * are provided via the same @flags values as documented in
+ * virDomainSnapshotListAllChildren().
  *
  * Returns the number of domain snapshots found or -1 in case of error.
  */
@@ -642,39 +564,12 @@ virDomainSnapshotNumChildren(virDomainSnapshotPtr snapshot, unsigned int flags)
  * earlier snapshot; otherwise, the order of snapshots in the
  * resulting list is unspecified.
  *
- * By default, this command covers only direct children; it is also possible
- * to expand things to cover all descendants, when @flags includes
- * VIR_DOMAIN_SNAPSHOT_LIST_DESCENDANTS.  Also, some filters are provided in
- * groups, where each group contains bits that describe mutually exclusive
- * attributes of a snapshot, and where all bits within a group describe
- * all possible snapshots.  Some hypervisors might reject explicit bits
- * from a group where the hypervisor cannot make a distinction.  For a
- * group supported by a given hypervisor, the behavior when no bits of a
- * group are set is identical to the behavior when all bits in that group
- * are set.  When setting bits from more than one group, it is possible to
- * select an impossible combination, in that case a hypervisor may return
- * either 0 or an error.
- *
- * The first group of @flags is VIR_DOMAIN_SNAPSHOT_LIST_LEAVES and
- * VIR_DOMAIN_SNAPSHOT_LIST_NO_LEAVES, to filter based on snapshots that
- * have no further children (a leaf snapshot).
- *
- * The next group of @flags is VIR_DOMAIN_SNAPSHOT_LIST_METADATA and
- * VIR_DOMAIN_SNAPSHOT_LIST_NO_METADATA, for filtering snapshots based on
- * whether they have metadata that would prevent the removal of the last
- * reference to a domain.
- *
- * The next group of @flags is VIR_DOMAIN_SNAPSHOT_LIST_INACTIVE,
- * VIR_DOMAIN_SNAPSHOT_LIST_ACTIVE, and VIR_DOMAIN_SNAPSHOT_LIST_DISK_ONLY,
- * for filtering snapshots based on what domain state is tracked by the
- * snapshot.
- *
- * The next group of @flags is VIR_DOMAIN_SNAPSHOT_LIST_INTERNAL and
- * VIR_DOMAIN_SNAPSHOT_LIST_EXTERNAL, for filtering snapshots based on
- * whether the snapshot is stored inside the disk images or as
- * additional files.
+ * By default, this command covers only direct children. It is also
+ * possible to expand things to cover all descendants, when @flags
+ * includes VIR_DOMAIN_SNAPSHOT_LIST_DESCENDANTS. Additional filters
+ * are provided via the same @flags values as documented in
+ * virDomainSnapshotListAllChildren().
  *
- * Returns the number of domain snapshots found or -1 in case of error.
  * Note that this command is inherently racy: another connection can
  * define a new snapshot between a call to virDomainSnapshotNumChildren()
  * and this call.  You are only guaranteed that all currently defined
@@ -725,7 +620,7 @@ virDomainSnapshotListChildrenNames(virDomainSnapshotPtr snapshot,
 /**
  * virDomainSnapshotListAllChildren:
  * @snapshot: a domain snapshot object
- * @snaps: pointer to variable to store the array containing snapshot objects,
+ * @snaps: pointer to variable to store the array containing snapshot objects
  *         or NULL if the list is not required (just returns number of
  *         snapshots)
  * @flags: bitwise-OR of supported virDomainSnapshotListFlags
@@ -742,37 +637,14 @@ virDomainSnapshotListChildrenNames(virDomainSnapshotPtr snapshot,
  * starting from that earlier snapshot; otherwise, the order of
  * snapshots in the resulting list is unspecified.
  *
- * By default, this command covers only direct children; it is also possible
- * to expand things to cover all descendants, when @flags includes
- * VIR_DOMAIN_SNAPSHOT_LIST_DESCENDANTS.  Also, some filters are provided in
- * groups, where each group contains bits that describe mutually exclusive
- * attributes of a snapshot, and where all bits within a group describe
- * all possible snapshots.  Some hypervisors might reject explicit bits
- * from a group where the hypervisor cannot make a distinction.  For a
- * group supported by a given hypervisor, the behavior when no bits of a
- * group are set is identical to the behavior when all bits in that group
- * are set.  When setting bits from more than one group, it is possible to
- * select an impossible combination, in that case a hypervisor may return
- * either 0 or an error.
- *
- * The first group of @flags is VIR_DOMAIN_SNAPSHOT_LIST_LEAVES and
- * VIR_DOMAIN_SNAPSHOT_LIST_NO_LEAVES, to filter based on snapshots that
- * have no further children (a leaf snapshot).
- *
- * The next group of @flags is VIR_DOMAIN_SNAPSHOT_LIST_METADATA and
- * VIR_DOMAIN_SNAPSHOT_LIST_NO_METADATA, for filtering snapshots based on
- * whether they have metadata that would prevent the removal of the last
- * reference to a domain.
- *
- * The next group of @flags is VIR_DOMAIN_SNAPSHOT_LIST_INACTIVE,
- * VIR_DOMAIN_SNAPSHOT_LIST_ACTIVE, and VIR_DOMAIN_SNAPSHOT_LIST_DISK_ONLY,
- * for filtering snapshots based on what domain state is tracked by the
- * snapshot.
- *
- * The next group of @flags is VIR_DOMAIN_SNAPSHOT_LIST_INTERNAL and
- * VIR_DOMAIN_SNAPSHOT_LIST_EXTERNAL, for filtering snapshots based on
- * whether the snapshot is stored inside the disk images or as
- * additional files.
+ * By default, this command covers only direct children. It is also
+ * possible to expand things to cover all descendants, when @flags
+ * includes VIR_DOMAIN_SNAPSHOT_LIST_DESCENDANTS. Additional filters
+ * are provided via the remaining @flags values as documented in
+ * virDomainListAllSnapshots(), with the exception that
+ * VIR_DOMAIN_SNAPSHOT_LIST_ROOTS is not supported (in fact,
+ * VIR_DOMAIN_SNAPSHOT_LIST_DESCENDANTS has the same bit value but
+ * opposite semantics of widening rather than narrowing the listing).
  *
  * Returns the number of domain snapshots found or -1 and sets @snaps to
  * NULL in case of error.  On success, the array stored into @snaps is