Merge lp:~elementary-apps/granite/document-contract-interface into lp:~elementary-pantheon/granite/granite

[Sergey "Shnatsel" Davidoff]

Documentation: Add descriptions for Granite.Services.Contract and Granite.Services.ContractorError.

Document Granite.Services.Contract interface to the extent of my knowledge: I know how Contractor works but I'm no good at Vala.

[lp:~elementary-apps/granite/document-contract-interface]

716. By Sergey "Shnatsel" Davidoff on 2014-04-08

document ContractorError.SERVICE_NOT_AVAILABLE

[Victor Martinez (victored)]

Great work!

The description for the Contract interface isn't very accurate. As the API is quite self-describing, it'd be better to keep it simple. For example:

"Interface for accessing contract actions and properties." instead of "Opaque object representing a Contractor action".
We could simply avoid "Returned by" as it's rarely used in Vala documentation and you'd have to list every method of ContractorProxy returning such objects.

That said, you've done a great job documenting the methods of the Contract interface and you're also providing proper guidance on handling ContractorError.SERVICE_NOT_AVAILABLE.

review: Needs Fixing

[lp:~elementary-apps/granite/document-contract-interface]

717. By Sergey "Shnatsel" Davidoff on 2014-04-09

Improve description of Services.Contract interface according to Victor's guidance

[Sergey "Shnatsel" Davidoff (shnatsel)]

Fixed, thanks!

Is this good to go now?

[Victor Martinez (victored)]

Absolutely!

review: Approve

=== modified file 'lib/Services/ContractorProxy.vala'
--- lib/Services/ContractorProxy.vala	2014-04-05 04:36:31 +0000
+++ lib/Services/ContractorProxy.vala	2014-04-09 00:03:36 +0000
@@ -20,11 +20,42 @@
 ***/
 
 namespace Granite.Services {
+    /**
+     * Interface for executing and accessing properties of Contractor actions
+     */
     public interface Contract : Object {
+
+        /**
+         * Returns the display name of the contract, already internationalized
+         *
+         * @return The internationalized value of the 'Name' key in the .contract file.
+         * As of 2014, Contractor uses gettext to handle internationalization.
+         */
         public abstract string get_display_name ();
+
+        /**
+         * Returns the description of the contract, already internationalized
+         *
+         * @return The internationalized value of the 'Description' key in the .contract file.
+         * As of 2014, Contractor uses gettext to handle internationalization.
+         */
         public abstract string get_description ();
+
+        /**
+         * Returns an icon for this contract
+         *
+         * @return {@link Glib.Icon} based on the 'Icon' key in the .contract file.
+         */
         public abstract Icon get_icon ();
+
+        /**
+         * Executes the action on the given file
+         */
         public abstract void execute_with_file (File file) throws Error;
+
+        /**
+         * Executes the action on the given list of files
+         */
         public abstract void execute_with_files (File[] files) throws Error;
     }
 
@@ -32,6 +63,15 @@
      * thrown by {@link Granite.Services.ContractorProxy}
      */
     public errordomain ContractorError {
+        /**
+         * Usually means that Contractor is not installed or not configured properly
+         *
+         * Contractor is not a compile-time dependency, so it is possible to
+         * install an application that uses it without installing Contractor.
+         *
+         * Upon receiving this error the application should disable its Contractor-related
+         * functionality, which typically means hiding the relevant UI elements.
+         */
         SERVICE_NOT_AVAILABLE
     }