[libvirt] [dbus PATCH v2 6/6] Use Documentation Annotations in D-Bus Interface XML

[Pavel Hrdina]

On Fri, Mar 23, 2018 at 05:58:04PM +0100, Katerina Koukiou wrote:
> Since we don't follow the exact naming of libvirt API for libvirt-dbus,
> documentation should clarify which API call is used internally each time.
> 
> Signed-off-by: Katerina Koukiou <kkoukiou at redhat.com>
> ---
>  data/org.libvirt.Connect.xml | 24 ++++++++++++++++
>  data/org.libvirt.Domain.xml  | 66 ++++++++++++++++++++++++++++++++++++++------
>  2 files changed, 82 insertions(+), 8 deletions(-)
> 
> diff --git a/data/org.libvirt.Connect.xml b/data/org.libvirt.Connect.xml
> index 787cd8d..9849abe 100644
> --- a/data/org.libvirt.Connect.xml
> +++ b/data/org.libvirt.Connect.xml
> @@ -4,51 +4,75 @@
>  <node name="/org/libvirt/connect">
>    <interface name="org.libvirt.Connect">
>      <method name="ListDomains">
> +      <annotation name="org.gtk.GDBus.DocString"
> +        value="See https://libvirt.org/html/libvirt-libvirt-domain.html#virConnectListDomains"/>

The function should be virConnectListAllDomains.  I'll fix that before
pushing.

>        <arg name="flags" type="u" direction="in"/>
>        <arg name="domains" type="ao" direction="out"/>
>      </method>
>      <method name="CreateXML">
> +      <annotation name="org.gtk.GDBus.DocString"
> +        value="See https://libvirt.org/html/libvirt-libvirt-domain.html#virDomainCreateXML"/>
>        <arg name="xml" type="s" direction="in"/>
>        <arg name="flags" type="u" direction="in"/>
>        <arg name="domain" type="o" direction="out"/>
>      </method>
>      <method name="DefineXML">
> +      <annotation name="org.gtk.GDBus.DocString"
> +        value="See https://libvirt.org/html/libvirt-libvirt-domain.html#virDomainDefineXML"/>
>        <arg name="xml" type="s" direction="in"/>
>        <arg name="domain" type="o" direction="out"/>
>      </method>
>      <signal name="DomainCrashed">
> +      <annotation name="org.gtk.GDBus.DocString"
> +        value="See https://libvirt.org/html/libvirt-libvirt-domain.html#VIR_DOMAIN_EVENT_CRASHED"/>
>        <arg name="reason" type="s"/>
>        <arg name="domain" type="o"/>
>      </signal>

I was thinking about these domain lifecycle signals and maybe we should
rewrite it into one signal and as a doc string we should mention the
event callback function, which describes the arguments as well
<https://libvirt.org/html/libvirt-libvirt-domain.html#virConnectDomainEventCallback>.

And unrelated to this patch itself, I've just noticed, that the XML
describes the first argument as reason, which is not correct, the code
sets the first argument to the domain name.  So I'm thinking about
having the signal like this:

    <signal name="Domain">
      <annotation name="org.gtk.GDBus.DocString"
        value="See https://libvirt.org/html/libvirt-libvirt-domain.html#virConnectDomainEventCallback"/>
      <arg name="event" type="s"/>
      <arg name="reason" type="s"/>
      <arg name="domain" type="o"/>
    </signal>

I'll fix the links for the other events to point to the callback
function and the domain lifecycle events can be fixed by followup
patches.

>      <signal name="DomainDefined">
> +      <annotation name="org.gtk.GDBus.DocString"
> +        value="See https://libvirt.org/html/libvirt-libvirt-domain.html#VIR_DOMAIN_EVENT_DEFINED"/>
>        <arg name="reason" type="s"/>
>        <arg name="domain" type="o"/>
>      </signal>
>      <signal name="DomainPMSuspended">
> +      <annotation name="org.gtk.GDBus.DocString"
> +        value="See https://libvirt.org/html/libvirt-libvirt-domain.html#VIR_DOMAIN_EVENT_SUSPENDED"/>
>        <arg name="reason" type="s"/>
>        <arg name="domain" type="o"/>
>      </signal>
>      <signal name="DomainResumed">
> +      <annotation name="org.gtk.GDBus.DocString"
> +        value="See https://libvirt.org/html/libvirt-libvirt-domain.html#VIR_DOMAIN_EVENT_RESUMED"/>
>        <arg name="reason" type="s"/>
>        <arg name="domain" type="o"/>
>      </signal>
>      <signal name="DomainShutdown">
> +      <annotation name="org.gtk.GDBus.DocString"
> +        value="See https://libvirt.org/html/libvirt-libvirt-domain.html#VIR_DOMAIN_EVENT_SHUTDOWN"/>
>        <arg name="reason" type="s"/>
>        <arg name="domain" type="o"/>
>      </signal>
>      <signal name="DomainStarted">
> +      <annotation name="org.gtk.GDBus.DocString"
> +        value="See https://libvirt.org/html/libvirt-libvirt-domain.html#VIR_DOMAIN_EVENT_STARTED"/>
>        <arg name="reason" type="s"/>
>        <arg name="domain" type="o"/>
>      </signal>
>      <signal name="DomainStopped">
> +      <annotation name="org.gtk.GDBus.DocString"
> +        value="See https://libvirt.org/html/libvirt-libvirt-domain.html#VIR_DOMAIN_EVENT_STOPPED"/>
>        <arg name="reason" type="s"/>
>        <arg name="domain" type="o"/>
>      </signal>
>      <signal name="DomainSuspended">
> +      <annotation name="org.gtk.GDBus.DocString"
> +        value="See https://libvirt.org/html/libvirt-libvirt-domain.html#VIR_DOMAIN_EVENT_SUSPENDED"/>
>        <arg name="reason" type="s"/>
>        <arg name="domain" type="o"/>
>      </signal>
>      <signal name="DomainUndefined">
> +      <annotation name="org.gtk.GDBus.DocString"
> +        value="See https://libvirt.org/html/libvirt-libvirt-domain.html#VIR_DOMAIN_EVENT_UNDEFINED"/>
>        <arg name="reason" type="s"/>
>        <arg name="domain" type="o"/>
>      </signal>
> diff --git a/data/org.libvirt.Domain.xml b/data/org.libvirt.Domain.xml
> index e79fb5e..4b927a8 100644
> --- a/data/org.libvirt.Domain.xml
> +++ b/data/org.libvirt.Domain.xml
> @@ -3,58 +3,108 @@
>  
>  <node name="/org/libvirt/domain">
>    <interface name="org.libvirt.Domain">
> -    <property name="Name" type="s" access="read"/>
> -    <property name="UUID" type="s" access="read"/>
> -    <property name="Id" type="u" access="read"/>
> -    <property name="OSType" type="s" access="read"/>
> -    <property name="Active" type="b" access="read"/>
> -    <property name="Persistent" type="b" access="read"/>
> -    <property name="State" type="s" access="read"/>
> -    <property name="Autostart" type="b" access="read"/>
> +    <property name="Name" type="s" access="read">
> +      <annotation name="org.gtk.GDBus.DocString"
> +        value="See https://libvirt.org/html/libvirt-libvirt-domain.html#virDomainGetName"/>
> +    </property>
> +    <property name="UUID" type="s" access="read">
> +      <annotation name="org.gtk.GDBus.DocString"
> +        value="See https://libvirt.org/html/libvirt-libvirt-domain.html#virDomainGetUUID"/>

This should be virDomainGetUUIDString, I'll fix that before pushing.

Pavel
-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 833 bytes
Desc: not available
URL: <http://listman.redhat.com/archives/libvir-list/attachments/20180326/3b404ada/attachment-0001.sig>