Merge lp:~shnatsel/granite/better-contractor-documentation into lp:~elementary-pantheon/granite/granite

[Sergey "Shnatsel" Davidoff]

ContractorProxy: Improve documentation.

Document Contractor-related stuff better.

[Victor Martinez (victored)]

Looks good!

I'm not sure about this line:

"Provides an easy way to interface with Contractor API from Vala"...

...since it also makes it easy to interface with C code. What about:

"Provides an easy way to interface with Contractor's DBus API" ?

[lp:~shnatsel/granite/better-contractor-documentation]

712. By Sergey "Shnatsel" Davidoff on 2014-04-05

Clarify ContractorProxy description, the API is not exclusive to Vala (hopefully)

[Victor Martinez (victored)]

review: Approve

=== modified file 'lib/Services/Contractor.vala'
--- lib/Services/Contractor.vala	2013-04-23 04:40:58 +0000
+++ lib/Services/Contractor.vala	2014-04-05 03:51:14 +0000
@@ -25,9 +25,7 @@
     }
 
     /**
-     * A way to handle contractor, a way to communicate between apps.
-     * 
-     * /!\ Highly unstable API
+     * Wrapper around a long-obsolete and unused revision of Contractor API
      */
     [Deprecated (replacement = "Granite.Services.ContractorProxy", since = "0.2")]
     public class Contractor : Object {

=== modified file 'lib/Services/ContractorProxy.vala'
--- lib/Services/ContractorProxy.vala	2013-10-04 12:04:45 +0000
+++ lib/Services/ContractorProxy.vala	2014-04-05 03:51:14 +0000
@@ -28,6 +28,9 @@
         public abstract void execute_with_files (File[] files) throws Error;
     }
 
+    /**
+     * thrown by {@link Granite.Services.ContractorProxy}
+     */
     public errordomain ContractorError {
         SERVICE_NOT_AVAILABLE
     }
@@ -50,6 +53,9 @@
         public abstract void execute_with_uri_list (string id, string[] uri) throws Error;
     }
 
+    /**
+     * Provides a convenient GObject wrapper around Contractor's D-bus API
+     */
     public class ContractorProxy : Object {
         private class GenericContract : Object, Contract {
             public string id { get; private set; }
@@ -109,6 +115,13 @@
             }
         }
 
+        /**
+         * Emitted when the list of actions available to Contractor changes.
+         * Application should generally request the updated list of actions upon receiving this signal.
+         *
+         * This is not obligatory for frequently updated lists (e.g. in context menus), 
+         * but essential for applications that display action lists without re-requesting them.
+         */
         public signal void contracts_changed ();
 
         private static ContractorDBusAPI contractor_dbus;