isa/gnome-shell
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

remote-search: properly document the DBus interface

Browse Source 
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
This commit is contained in:
Cosimo Cecchi 2012-12-05 14:37:57 -05:00
parent 6822795bb8
commit 1ef9ee13a3
4 changed files with 63 additions and 129 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

1
.gitignore vendored
View File

@ -38,6 +38,7 @@ docs/reference/*/*.txt
docs/reference/*/*.types docs/reference/*/*.types
docs/reference/*/html/ docs/reference/*/html/
docs/reference/*/xml/ docs/reference/*/xml/
docs/reference/shell/doc-gen-*
gtk-doc.make gtk-doc.make
js/misc/config.js js/misc/config.js
intltool-extract.in intltool-extract.in

166
data/org.gnome.ShellSearchProvider.xml
View File

@ -2,146 +2,72 @@
'-//freedesktop//DTD D-BUS Object Introspection 1.0//EN' '-//freedesktop//DTD D-BUS Object Introspection 1.0//EN'
'http://www.freedesktop.org/standards/dbus/1.0/introspect.dtd'> 'http://www.freedesktop.org/standards/dbus/1.0/introspect.dtd'>
<node> <node>
<interface name="org.gnome.Shell.SearchProvider">
<doc:doc> <!--
<doc:description> org.gnome.Shell.SearchProvider:
<doc:para> @short_description: Search provider interface
The interface used for integrating into GNOME Shell's search The interface used for integrating into GNOME Shell's search
interface. interface.
</doc:para> -->
</doc:description> <interface name="org.gnome.Shell.SearchProvider">
</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.
<method name="GetInitialResultSet">
<doc:doc>
<doc:description>
<doc:para>
Called when the user first begins a search. Called when the user first begins a search.
</doc:para> -->
</doc:description> <method name="GetInitialResultSet">
</doc:doc> <arg type="as" name="terms" direction="in" />
<arg type="as" direction="in"> <arg type="as" name="results" direction="out" />
<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>
</method> </method>
<method name="GetSubsearchResultSet"> <!--
<doc:doc> GetSubsearchResultSet:
<doc:description> @previous_results: Array of results previously returned by GetInitialResultSet().
<doc:para> @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 Called when a search is performed which is a "subsearch" of
the previous search, e.g. the method may return less results, but the previous search, e.g. the method may return less results, but
not more or different results. not more or different results.
This allows search providers to only search through the previous This allows search providers to only search through the previous
result set, rather than possibly performing a full re-query. result set, rather than possibly performing a full re-query.
</doc:para> -->
</doc:description> <method name="GetSubsearchResultSet">
</doc:doc> <arg type="as" name="previous_results" direction="in" />
<arg type="as" direction="in"> <arg type="as" name="terms" direction="in" />
<doc:doc> <arg type="as" name="results" direction="out" />
<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>
</method> </method>
<method name="GetResultMetas"> <!--
<doc:doc> GetResultMetas:
<doc:description> @identifiers: An array of result identifiers as returned by GetInitialResultSet() or GetSubsearchResultSet()
<doc:para> @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 Return an array of meta data used to display each given result
</doc:para> -->
</doc:description> <method name="GetResultMetas">
</doc:doc> <arg type="as" name="identifiers" direction="in" />
<arg type="as" direction="in"> <arg type="aa{sv}" name="metas" direction="out" />
<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>
</method> </method>
<method name="ActivateResult"> <!--
<doc:doc> ActivateResult:
<doc:description> @identifier: A result identifier as returned by GetInitialResultSet() or GetSubsearchResultSet()
<doc:para>
Called when the users chooses a given result. The result should Called when the users chooses a given result. The result should
be displayed in the application associated with the corresponding be displayed in the application associated with the corresponding
provider. provider.
</doc:para>
</doc:description> This method is deprecated, and providers should implement ActivateResult2()
</doc:doc> instead.
<arg type="s" direction="in"> -->
<doc:doc> <method name="ActivateResult">
<doc:summary> <arg type="s" name="identifier" direction="in" />
<doc:para>
A result identifier as returned by GetInitialResultSet() or
GetSubsearchResultSet()
</doc:para>
</doc:summary>
</doc:doc>
</arg>
</method> </method>
</interface> </interface>
</node> </node>

8
docs/reference/shell/Makefile.am
View File

@ -76,9 +76,15 @@ endif
# e.g. HTML_IMAGES=$(top_srcdir)/gtk/stock-icons/stock_about_24.png # e.g. HTML_IMAGES=$(top_srcdir)/gtk/stock-icons/stock_about_24.png
HTML_IMAGES= 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). # Extra SGML files that are included by $(DOC_MAIN_SGML_FILE).
# e.g. content_files=running.sgml building.sgml changes-2.0.sgml # 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 # SGML files where gtk-doc abbrevations (#GtkWidget) are expanded
# These files must be listed here *and* in content_files # These files must be listed here *and* in content_files

1
docs/reference/shell/shell-docs.sgml.in
View File

@ -43,6 +43,7 @@
</chapter> </chapter>
<chapter> <chapter>
<title>Integration helpers and utilities</title> <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-global.xml"/>
<xi:include href="xml/shell-wm.xml"/> <xi:include href="xml/shell-wm.xml"/>
<xi:include href="xml/shell-xfixes-cursor.xml"/> <xi:include href="xml/shell-xfixes-cursor.xml"/>