GNOME.org
 

[gnome-shell] remote-search: properly document the DBus interface

commit 1ef9ee13a3c3f82444e33c5eac49e6c983148551
Author: Cosimo Cecchi <cosimoc gnome org>
Date:   Wed Dec 5 14:37:57 2012 -0500

    remote-search: properly document the DBus interface
    
    Use real annotations in the XML, and use gdbus-codegen to extract those
    into docbook. We then include it in the Shell's gtk-doc.
    
    https://bugzilla.gnome.org/show_bug.cgi?id=689735

 .gitignore                              |    1 +
 data/org.gnome.ShellSearchProvider.xml  |  182 +++++++++----------------------
 docs/reference/shell/Makefile.am        |    8 +-
 docs/reference/shell/shell-docs.sgml.in |    1 +
 4 files changed, 63 insertions(+), 129 deletions(-)
---
diff --git a/.gitignore b/.gitignore
index eee501a..9154c71 100644
--- a/.gitignore
+++ b/.gitignore
@@ -38,6 +38,7 @@ docs/reference/*/*.txt
 docs/reference/*/*.types
 docs/reference/*/html/
 docs/reference/*/xml/
+docs/reference/shell/doc-gen-*
 gtk-doc.make
 js/misc/config.js
 intltool-extract.in
diff --git a/data/org.gnome.ShellSearchProvider.xml b/data/org.gnome.ShellSearchProvider.xml
index 558e662..8a7ab2c 100644
--- a/data/org.gnome.ShellSearchProvider.xml
+++ b/data/org.gnome.ShellSearchProvider.xml
@@ -2,146 +2,72 @@
 '-//freedesktop//DTD D-BUS Object Introspection 1.0//EN'
 'http://www.freedesktop.org/standards/dbus/1.0/introspect.dtd'>
 <node>
+
+  <!--
+      org.gnome.Shell.SearchProvider:
+      @short_description: Search provider interface
+
+      The interface used for integrating into GNOME Shell's search
+      interface.
+  -->
   <interface name="org.gnome.Shell.SearchProvider">
-    <doc:doc>
-      <doc:description>
-        <doc:para>
-          The interface used for integrating into GNOME Shell's search
-          interface.
-        </doc:para>
-      </doc:description>
-    </doc:doc>
 
+    <!--
+        GetInitialResultSet:
+        @terms: Array of search terms, which the provider should treat as logical AND.
+        @results: An array of result identifier strings representing items which match the given search terms. Identifiers must be unique within the provider's domain, but other than that may be chosen freely by the provider.
+
+        Called when the user first begins a search.
+    -->
     <method name="GetInitialResultSet">
-      <doc:doc>
-        <doc:description>
-          <doc:para>
-            Called when the user first begins a search.
-          </doc:para>
-        </doc:description>
-      </doc:doc>
-      <arg type="as" direction="in">
-        <doc:doc>
-          <doc:summary>
-            <doc:para>
-              Array of search terms, which the provider should treat as
-              logical AND.
-            </doc:para>
-          </doc:summary>
-        </doc:doc>
-      </arg>
-      <arg type="as" direction="out">
-        <doc:doc>
-          <doc:summary>
-            <doc:para>
-              An array of result identifier strings representing items which
-              match the given search terms. Identifiers must be unique within
-              the provider's domain, but other than that may be chosen freely
-              by the provider.
-            </doc:para>
-          </doc:summary>
-        </doc:doc>
-      </arg>
+      <arg type="as" name="terms" direction="in" />
+      <arg type="as" name="results" direction="out" />
     </method>
 
-    <method name="GetSubsearchResultSet">
-      <doc:doc>
-        <doc:description>
-          <doc:para>
-            Called when a search is performed which is a "subsearch" of
-            the previous search, e.g. the method may return less results, but
-            not more or different results.
+    <!--
+        GetSubsearchResultSet:
+        @previous_results: Array of results previously returned by GetInitialResultSet().
+        @terms: Array of updated search terms, which the provider should treat as logical AND.
+        @results: An array of result identifier strings representing items which match the given search terms. Identifiers must be unique within the provider's domain, but other than that may be chosen freely by the provider.
+
+        Called when a search is performed which is a "subsearch" of
+        the previous search, e.g. the method may return less results, but
+        not more or different results.
 
-            This allows search providers to only search through the previous
-            result set, rather than possibly performing a full re-query.
-          </doc:para>
-        </doc:description>
-      </doc:doc>
-      <arg type="as" direction="in">
-        <doc:doc>
-          <doc:summary>
-            <doc:para>
-              Array of item identifiers
-            </doc:para>
-          </doc:summary>
-        </doc:doc>
-      </arg>
-      <arg type="as" direction="in">
-        <doc:doc>
-          <doc:summary>
-            <doc:para>
-              Array of updated search terms, which the provider should treat as
-              logical AND.
-            </doc:para>
-          </doc:summary>
-        </doc:doc>
-      </arg>
-      <arg type="as" direction="out">
-        <doc:doc>
-          <doc:summary>
-            <doc:para>
-              An array of result identifier strings representing items which
-              match the given search terms. Identifiers must be unique within
-              the provider's domain, but other than that may be chosen freely
-              by the provider.
-            </doc:para>
-          </doc:summary>
-        </doc:doc>
-      </arg>
+        This allows search providers to only search through the previous
+        result set, rather than possibly performing a full re-query.
+    -->
+    <method name="GetSubsearchResultSet">
+      <arg type="as" name="previous_results" direction="in" />
+      <arg type="as" name="terms" direction="in" />
+      <arg type="as" name="results" direction="out" />
     </method>
 
+    <!--
+        GetResultMetas:
+        @identifiers: An array of result identifiers as returned by GetInitialResultSet() or GetSubsearchResultSet()
+        @metas: A dictionary describing the given search result, containing 'id' and 'name' (both strings). Optionally, either 'gicon' (a serialized GIcon) or 'icon-data' (raw image data as (iiibiiay) - width, height, rowstride, has-alpha, bits per sample, channels, data) can be specified if the result can be better served with a thumbnail of the content (such as with images).
+
+        Return an array of meta data used to display each given result
+    -->
     <method name="GetResultMetas">
-      <doc:doc>
-        <doc:description>
-          <doc:para>
-            Return an array of meta data used to display each given result
-          </doc:para>
-        </doc:description>
-      </doc:doc>
-      <arg type="as" direction="in">
-        <doc:doc>
-          <doc:summary>
-            <doc:para>
-              An array of result identifiers as returned by
-              GetInitialResultSet() or GetSubsearchResultSet()
-            </doc:para>
-          </doc:summary>
-        </doc:doc>
-      </arg>
-      <arg type="aa{sv}" direction="out">
-        <doc:doc>
-          <doc:summary>
-            <doc:para>
-              A dictionary describing the given search result, containing
-              'id', 'name' (both strings) and either 'icon' (a serialized
-              GIcon) or 'icon-data' (raw image data as (iiibiiay) - width,
-              height, rowstride, has-alpha, bits per sample, channels, data)
-            </doc:para>
-          </doc:summary>
-        </doc:doc>
-      </arg>
+      <arg type="as" name="identifiers" direction="in" />
+      <arg type="aa{sv}" name="metas" direction="out" />
     </method>
 
+    <!--
+        ActivateResult:
+        @identifier: A result identifier as returned by GetInitialResultSet() or GetSubsearchResultSet()
+
+        Called when the users chooses a given result. The result should
+        be displayed in the application associated with the corresponding
+        provider.
+
+        This method is deprecated, and providers should implement ActivateResult2()
+        instead.
+    -->
     <method name="ActivateResult">
-      <doc:doc>
-        <doc:description>
-          <doc:para>
-            Called when the users chooses a given result. The result should
-            be displayed in the application associated with the corresponding
-            provider.
-          </doc:para>
-        </doc:description>
-      </doc:doc>
-      <arg type="s" direction="in">
-        <doc:doc>
-          <doc:summary>
-            <doc:para>
-              A result identifier as returned by GetInitialResultSet() or
-              GetSubsearchResultSet()
-            </doc:para>
-          </doc:summary>
-        </doc:doc>
-      </arg>
+      <arg type="s" name="identifier" direction="in" />
     </method>
   </interface>
 </node>
diff --git a/docs/reference/shell/Makefile.am b/docs/reference/shell/Makefile.am
index b79bc7b..2bb0395 100644
--- a/docs/reference/shell/Makefile.am
+++ b/docs/reference/shell/Makefile.am
@@ -76,9 +76,15 @@ endif
 # e.g. HTML_IMAGES=$(top_srcdir)/gtk/stock-icons/stock_about_24.png
 HTML_IMAGES=
 
+doc-gen-org.gnome.Shell.SearchProvider.xml: $(top_srcdir)/data/org.gnome.ShellSearchProvider.xml
+	gdbus-codegen 						\
+	--interface-prefix org.gnome.ShellSearchProvider. 	\
+	--generate-docbook doc-gen				\
+	$(top_srcdir)/data/org.gnome.ShellSearchProvider.xml
+
 # Extra SGML files that are included by $(DOC_MAIN_SGML_FILE).
 # e.g. content_files=running.sgml building.sgml changes-2.0.sgml
-content_files=
+content_files= doc-gen-org.gnome.Shell.SearchProvider.xml
 
 # SGML files where gtk-doc abbrevations (#GtkWidget) are expanded
 # These files must be listed here *and* in content_files
diff --git a/docs/reference/shell/shell-docs.sgml.in b/docs/reference/shell/shell-docs.sgml.in
index 72149a5..c2d8748 100644
--- a/docs/reference/shell/shell-docs.sgml.in
+++ b/docs/reference/shell/shell-docs.sgml.in
@@ -43,6 +43,7 @@
   </chapter>
   <chapter>
     <title>Integration helpers and utilities</title>
+    <xi:include href="doc-gen-org.gnome.Shell.SearchProvider.xml"/>
     <xi:include href="xml/shell-global.xml"/>
     <xi:include href="xml/shell-wm.xml"/>
     <xi:include href="xml/shell-xfixes-cursor.xml"/>
[Date Prev][Date Next]   [Thread Prev][Thread Next]   [Thread Index] [Date Index] [Author Index]