From 1ef9ee13a3c3f82444e33c5eac49e6c983148551 Mon Sep 17 00:00:00 2001 From: Cosimo Cecchi Date: Wed, 5 Dec 2012 14:37:57 -0500 Subject: [PATCH] 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 eee501adc..9154c71e9 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 558e6620c..8a7ab2cfd 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'> + + - - - - The interface used for integrating into GNOME Shell's search - interface. - - - + - - - - Called when the user first begins a search. - - - - - - - - Array of search terms, which the provider should treat as - logical AND. - - - - - - - - - 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. - - - - - - - - Array of item identifiers - - - - - - - - - Array of updated search terms, which the provider should treat as - logical AND. - - - - - - - - - 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. - - - - + + + + - - - - Return an array of meta data used to display each given result - - - - - - - - An array of result identifiers as returned by - GetInitialResultSet() or GetSubsearchResultSet() - - - - - - - - - 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) - - - - + + + - - - - Called when the users chooses a given result. The result should - be displayed in the application associated with the corresponding - provider. - - - - - - - - A result identifier as returned by GetInitialResultSet() or - GetSubsearchResultSet() - - - - + diff --git a/docs/reference/shell/Makefile.am b/docs/reference/shell/Makefile.am index b79bc7be2..2bb039542 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 72149a559..c2d874803 100644 --- a/docs/reference/shell/shell-docs.sgml.in +++ b/docs/reference/shell/shell-docs.sgml.in @@ -43,6 +43,7 @@ Integration helpers and utilities +