virDomainSnapshotAlignDisks: Improve function comment

Add description of arguments, reword the description for clarity, and
fix improper argument names mentioned in the existing description.

Signed-off-by: Peter Krempa <pkrempa@redhat.com>
Reviewed-by: Ján Tomko <jtomko@redhat.com>

diff --git a/src/conf/snapshot_conf.c b/src/conf/snapshot_conf.c
index d46d9bd335d1041d6c2ef0f3614fdd6f7d09a372..d7e18596bc73b0f9e11812c99ee5bd8fbc49ce9c 100644 (file)
--- a/src/conf/snapshot_conf.c
+++ b/src/conf/snapshot_conf.c
@@ -622,13 +622,22 @@ virDomainSnapshotDefAssignExternalNames(virDomainSnapshotDef *def)
 }
 
 
-/* Align def->disks to def->parent.dom.  Sort the list of def->disks,
- * filling in any missing disks or snapshot state defaults given by
- * the domain, with a fallback to a passed in default.  Convert paths
- * to disk targets for uniformity.  Issue an error and return -1 if
- * any def->disks[n]->name appears more than once or does not map to
- * dom->disks.  If require_match, also ensure that there is no
- * conflicting requests for both internal and external snapshots.  */
+/**
+ * virDomainSnapshotAlignDisks:
+ * @snapdef: Snapshot definition to align
+ * @default_snapshot: snapshot location to assign to disks which don't have any
+ * @require_match: Require that all disks use the same snapshot mode
+ *
+ * Align snapdef->disks to snapdef->parent.dom, filling in any missing disks or
+ * snapshot state defaults given by the domain, with a fallback to
+ * @default_snapshot. Ensure that there are no duplicate snapshot disk
+ * definitions in @snapdef and there are no disks described in @snapdef but
+ * missing from the domain definition.
+ *
+ * Convert paths to disk targets for uniformity.
+ *
+ * On error -1 is returned and a libvirt error is reported.
+ */
 int
 virDomainSnapshotAlignDisks(virDomainSnapshotDef *snapdef,
                             int default_snapshot,