[libvirt] [PATCHv2] Clarify behavior or virDomainDetachDevice

[Ján Tomko]

Document that a complete device definition should be used
and a partial match can lead to the device being detached.

https://bugzilla.redhat.com/show_bug.cgi?id=872028
---
 src/libvirt-domain.c | 14 ++++++++++++++
 tools/virsh.pod      |  9 ++++++---
 2 files changed, 20 insertions(+), 3 deletions(-)

diff --git a/src/libvirt-domain.c b/src/libvirt-domain.c
index 492e90a..fb85a28 100644
--- a/src/libvirt-domain.c
+++ b/src/libvirt-domain.c
@@ -8266,6 +8266,13 @@ virDomainAttachDeviceFlags(virDomainPtr domain,
  * into S4 state (also known as hibernation) unless you also modify the
  * persistent domain definition.
  *
+ * The supplied XML description of the device should be as specific
+ * as its definition in the domain XML. The set of attributes used
+ * to match the device are internal to the drivers. Using a partial definition,
+ * or attempting to detach a device that is not present in the domain XML,
+ * but shares some specific attributes with one that is present
+ * may lead to unexpected results.
+ *
  * Returns 0 in case of success, -1 in case of failure.
  */
 int
@@ -8341,6 +8348,13 @@ virDomainDetachDevice(virDomainPtr domain, const char *xml)
  * into S4 state (also known as hibernation) unless you also modify the
  * persistent domain definition.
  *
+ * The supplied XML description of the device should be as specific
+ * as its definition in the domain XML. The set of attributes used
+ * to match the device are internal to the drivers. Using a partial definition,
+ * or attempting to detach a device that is not present in the domain XML,
+ * but shares some specific attributes with one that is present
+ * may lead to unexpected results.
+ *
  * Returns 0 in case of success, -1 in case of failure.
  */
 int
diff --git a/tools/virsh.pod b/tools/virsh.pod
index 50de32c..09663f5 100644
--- a/tools/virsh.pod
+++ b/tools/virsh.pod
@@ -2439,9 +2439,12 @@ as command B<attach-device>.
 For passthrough host devices, see also B<nodedev-reattach>, needed if
 the device does not use managed mode.
 
-B<Note>: using of partial device definition XML files may lead to unexpected
-results as some fields may be autogenerated and thus match devices other than
-expected.
+B<Note>: The supplied XML description of the device should be as specific
+as its definition in the domain XML. The set of attributes used
+to match the device are internal to the drivers. Using a partial definition,
+or attempting to detach a device that is not present in the domain XML,
+but shares some specific attributes with one that is present
+may lead to unexpected results.
 
 If I<--live> is specified, affect a running domain.
 If I<--config> is specified, affect the next startup of a persistent domain.
-- 
2.0.5