Merge lp:~robru/libfriends/valadoc into lp:libfriends

[Robert Bruce Park]

Ok, writing this all out was easier than I thought it was gonna be ;-)

Some of the vala constructors looked a little bit weird to me so you should definitely have a look at this and see if you can't chime in with extra info where you feel stuff is missing. But I'd say it's 90% done.

[Robert Bruce Park (robru)]

This mp also contains a bunch of whitespace cleanup, because you suck at indenting things properly :-P

=== modified file 'gtk/account.vala'
--- gtk/account.vala	2012-12-10 18:06:49 +0000
+++ gtk/account.vala	2013-01-05 00:43:20 +0000
@@ -18,34 +18,86 @@
  */
 
 
+    /**
+     * This is a thin wrapper around {@link Ag.Account}.
+     *
+     * @since 0.1
+     */
     class FriendsAccount : GLib.Object {
         private Ag.Account _account = null;
-        [Description(id = "Friends account id", blurb = "This is id Friends uses to identify the account")]
+
+        /**
+         * String that uniquely identifies the account. It takes the
+         * form of '#/protocol', where # is the {@link Ag.Account.id}
+         * and protocol is the lowercase name of the social network
+         * that the account is from. Possible values include
+         * '6/facebook' or '2/twitter'. The number on it's own is
+         * unique (so you'd never see '1/twitter' and '1/facebook' on
+         * the same system), but we do support registering multiple
+         * accounts per protocol, so finding '1/twitter', '2/twitter',
+         * and '3/twitter' is perfectly acceptable.
+         *
+         * @since 0.1
+         */
         public string id {
             get { return unique_id; }
         }
-        [Description(username = "username associated with an account", blurb = "This is the account's username assigned by the service")]
+
+        /**
+         * This is the username that the social network uses to
+         * identify the user. For example on twitter, this is the name
+         * that people use to @mention you in their tweets.
+         *
+         * @since 0.1
+         */
         public string username {
             get { return _account.get_display_name(); }
         }
+
+        /**
+         * This is the bare name of the protocol. Possible values are
+         * ``facebook``, ``foursquare``, ``flickr``, ``identica``, and
+         * ``twitter``.
+         *
+         * @since 0.1
+         */
         public string service {
             get { return _account.get_provider_name(); }
         }
 
+        /**
+         * A single, solid color used to represent the given protocol.
+         * This is stored as a familiar HTML style hex triplet, in the
+         * form of 'RRGGBB'.
+         *
+         * @since 0.1
+         */
         private string _color;
-        public string color { 
+        public string color {
             get {
               GLib.Value t = "";
               _account.get_value("friends/color", ref t);
               _color = t.get_string();
               return _color;
             }
-            set { 
+            set {
               GLib.Value t = value;
-              _account.set_value("friends/color", t); 
+              _account.set_value("friends/color", t);
               _account.store_blocking();
             }
         }
+
+        /**
+         * Controls whether this account should be included in the
+         * global ``send_message`` call. If you want to send a
+         * particular message to some, but not all accounts, you can
+         * use this to effectively 'disable' the account.
+         *
+         * Set to the string "1" to enable and the string "0" to disable.
+         *
+         * @since 0.1
+         * @see toggle_send_enabled
+         */
         private string? _send_enabled;
         public string? send_enabled {
             get {
@@ -61,7 +113,7 @@
                 _send_enabled = "0";
               return _send_enabled;
             }
-            set { 
+            set {
               GLib.Value t = false;
               if (value == "1")
                 t = true;
@@ -73,20 +125,31 @@
         private Ag.AccountService account_service;
         private string unique_id;
 
-        /** 
-            FriendsAccount::updated:
-
-            Emitted when the account has changed
-        */
+        /**
+         * Emitted when the account has changed, most useful for being
+         * notified of changes to {@link send_enabled}.
+         *
+         * @since 0.1
+         */
         public signal void updated();
 
-        /** 
-            FriendsAccount::deleted:
-
-            Emitted when the account has been deleted
-        */
+        /**
+         * Emitted when the account has been deleted. This happens
+         * when the user deletes the account from the Ubuntu Online
+         * Accounts screen.
+         *
+         * @since 0.1
+         */
         public signal void deleted();
 
+        /**
+         * Construct a new FriendsAccount object.
+         *
+         * @params account_service The {@link Ag.AccountService}
+         * object that our FriendsAccount will be wrapping.
+         *
+         * @since 0.1
+         */
         public FriendsAccount (Ag.AccountService account_service) {
             this.account_service = account_service;
             _account = account_service.get_account();
@@ -103,10 +166,11 @@
         }
 
         /**
-            toggle_send_enabled:
-
-            Toggle the value of send_enabled for the account.
-        */
+         * Toggle the value of send_enabled for the account.
+         *
+         * @since 0.1
+         * @see send_enabled
+         */
         public void toggle_send_enabled()
         {
             if (send_enabled == "1")

=== modified file 'gtk/accounts.vala'
--- gtk/accounts.vala	2012-12-07 22:01:20 +0000
+++ gtk/accounts.vala	2013-01-05 00:43:20 +0000
@@ -23,12 +23,6 @@
     {
         private Ag.Manager manager;
 
-        /** 
-            FriendsAccounts::created:
-            @arg0: HashTable of an account
-
-            Emitted when an account has changed
-        */
         internal signal void created(FriendsAccount account);
 
         internal FriendsAccounts()

=== modified file 'gtk/entry.vala'
--- gtk/entry.vala	2013-01-04 22:19:27 +0000
+++ gtk/entry.vala	2013-01-05 00:43:20 +0000
@@ -23,16 +23,18 @@
 {
     public static const int MAX_MESSAGE_LENGTH = 140;
 
-   /**
-    * Widget that displays an entry which posts status updates to your 
-    * social network accounts using friends-service.  The entry includes 
-    * a text entry, character count, and account selection buttons.
-    */
+    /**
+     * Widget that displays an entry which posts status updates to your
+     * social network accounts using friends-service.  The entry includes
+     * a text entry, character count, and account selection buttons.
+     *
+     * @since 0.1
+     */
     public class Entry : Gtk.Box
     {
-       /**
-        * {@link Friends.Service}
-        */
+        /**
+         * {@link Friends.Service}
+         */
         private Friends.Service service;
 
         public InputTextView text_view;
@@ -63,15 +65,26 @@
             var spacer = new Gtk.Box (Gtk.Orientation.HORIZONTAL, 0);
             add_with_properties (spacer, "padding", 2, "expand", false);
 
-            text_view.get_buffer ().changed.connect (() => 
+            text_view.get_buffer ().changed.connect (() =>
             {
               target_bar.set_counter(text_view.get_buffer ().get_char_count ());
             });
         }
     }
 
+    /**
+     * Widget that displays an entry which posts status updates to
+     * your social network accounts using friends-service. The entry
+     * is very simple and does not include any of the frills of {@link
+     * FriendsGtk.Entry}.
+     *
+     * @since 0.1
+     */
     public class SimpleEntry : Gtk.Box
     {
+        /**
+         * {@link Friends.Service}
+         */
         private Friends.Service service;
 
         private InputTextView text_view;
@@ -85,7 +98,7 @@
         construct
         {
             service = new Friends.Service ();
-            
+
             text_view = new InputTextView (service);
             send_bar = new SendBar ();
             add (text_view);
@@ -96,11 +109,18 @@
                 text_view.submit ();});
         }
 
-
     }
 
+    /**
+     * Just the text box.
+     *
+     * @since 0.1
+     */
     public class InputTextView : Gtk.TextView
     {
+        /**
+         * {@link Friends.Service}
+         */
         private Friends.Service service;
         private Friends.URLShorten urlshorten;
 
@@ -188,7 +208,7 @@
         [Signal (action=true)]
         public virtual signal void clear() {
             buffer.set_text("");
-	}
+        }
 
         [Signal (action=true)]
         public virtual signal void submit () {
@@ -213,9 +233,9 @@
         }
 
         private void on_connection_changed (bool is_connected)
-	{
-		set_sensitive(is_connected);
-	}
+        {
+            set_sensitive(is_connected);
+        }
 
         private void on_text_changed ()
         {
@@ -244,10 +264,17 @@
         }
     }
 
+    /**
+     * This toggle button toggles an individual account on or off.
+     *
+     * @since 0.1
+     */
     public class AccountToggleButton : Gtk.ToggleButton
     {
        /**
-        * color used to differentiate accounts
+        * The color is used to differentiate accounts.
+        *
+        * @since 0.1
         */
         public string color {  get; construct;}
         public AccountToggleButton (string color)
@@ -260,7 +287,7 @@
           set_size_request (24, 24);
         }
 
-        internal override bool draw (Cairo.Context context) 
+        internal override bool draw (Cairo.Context context)
         {
             double factor = 0.3;
 
@@ -278,7 +305,7 @@
 
             Gtk.Allocation a;
             get_allocation (out a);
-            
+
             Gdk.RGBA c = Gdk.RGBA ();
             c.red = 1.0f;
             c.green = 1.0f;
@@ -291,9 +318,9 @@
             context.rectangle (a.width - 2, a.height - 6, 2, 6);
             context.rectangle (a.width - 6, a.height - 2, 6, 2);
             context.fill ();
-            
+
             propagate_draw (get_child (), context);
-                        
+
             context.pop_group_to_source ();
             context.paint_with_alpha (factor);
 
@@ -301,13 +328,20 @@
         }
     }
 
+    /**
+     * The target bar displays a row of {@link AccountToggleButton}s
+     * to allow the user to choose which accounts to send the message
+     * to.
+     *
+     * @since 0.1
+     */
     public class AccountTargetBar : Gtk.Box
     {
         private Friends.Service service;
         private FriendsAccounts accounts_service;
         private Gtk.Button send;
         private Gtk.Label count;
-	private Gee.HashMap<string,AccountToggleButton> accounts_buttons_map;
+        private Gee.HashMap<string,AccountToggleButton> accounts_buttons_map;
         private Gtk.Box abox;
         private string _selected = null;
 
@@ -336,7 +370,7 @@
                     }
                     accounts_buttons_map[_selected].show_all ();
                   }
-                } else 
+                } else
                 {
                   foreach (var k in accounts_buttons_map.keys)
                     accounts_buttons_map[k].sensitive = true;
@@ -370,7 +404,7 @@
             accounts_buttons_map = new Gee.HashMap<string,AccountToggleButton> ();
 
             var accounts_list = accounts_service.list ();
-            
+
             abox = new Gtk.Box (Gtk.Orientation.HORIZONTAL, 6);
             abox.set_homogeneous (true);
             box.pack_start (abox, false, false, 0);
@@ -411,15 +445,15 @@
                 account_created(accounts_buttons_map, source);});
         }
 
-       /**
-        * Signal emitted when submitted to the service
-        */
+        /**
+         * Signal emitted when submitted to the service.
+         */
         public signal void submit ();
 
         private AccountToggleButton create_button (FriendsAccount account)
-        { 
+        {
             Gtk.Image icon_service = new Gtk.Image.from_icon_name(account.service, Gtk.IconSize.MENU);
-  
+
             icon_service.show();
             AccountToggleButton account_button = new AccountToggleButton(account.color);
             account_button.set_active((account.send_enabled == "1")?true:false);
@@ -459,13 +493,13 @@
 
         private void on_account_toggled(AccountToggleButton account_button, FriendsAccount account) {
 
-	    if (((account.send_enabled == "1")?true:false) !=  (account_button.get_active()))
+        if (((account.send_enabled == "1")?true:false) !=  (account_button.get_active()))
             {
                 account.toggle_send_enabled();
             }
         }
 
-        private void account_updated(Gee.HashMap<string,AccountToggleButton> accounts_buttons_map, FriendsAccount account) 
+        private void account_updated(Gee.HashMap<string,AccountToggleButton> accounts_buttons_map, FriendsAccount account)
         {
             if (!accounts_buttons_map.has_key(account.id))
                 return;
@@ -475,7 +509,7 @@
             } else {
                 account_button.tooltip_text = (account.service + " (" + account.username + ")");
             }
-	    if (((account.send_enabled == "1")?true:false) !=  (account_button.get_active())) {
+        if (((account.send_enabled == "1")?true:false) !=  (account_button.get_active())) {
                 account_button.set_active((account.send_enabled == "1")?true:false);
             }
         }
@@ -503,7 +537,7 @@
 
         private void on_connection_changed (bool is_connected) {
                 send.set_sensitive(is_connected);
-        } 
+        }
     }
 
     public class SendBar : Gtk.Box
@@ -525,9 +559,10 @@
             box.pack_end(send, false, false, 0);
             add(box);
         }
-       /**
-        * Signal emitted when submitted to the service
-        */
+
+        /**
+         * Signal emitted when submitted to the service.
+         */
         public signal void submit ();
     }
 }

=== modified file 'src/service.vala'
--- src/service.vala	2013-01-04 17:04:59 +0000
+++ src/service.vala	2013-01-05 00:43:20 +0000
@@ -46,24 +46,12 @@
 
         private ServiceInterface service;
 
-        /** 
-            Service::is_available:
-            @arg0: The current state
-
-            Emitted when com.canonical.Friends.Service availability state changes
-        */
         public signal void is_available(bool is_up);
 
-        /**
-            Service::connection_changed:
-            @arg0: The current state
-
-            Emitted when network connection state changes
-        */
         public signal void connection_changed(bool is_online);
 
        /**
-        * Create a new Service
+        * Establish a connection to the local Friends Service daemon.
         */
         public Service ()
         {
@@ -82,16 +70,19 @@
             }
         }
 
-	public void service_available(bool is_up)
-	{
-		is_available(is_up);
-	}
+        public void service_available(bool is_up)
+        {
+            is_available(is_up);
+        }
 
         /**
-            quit:
-
-            Tells the friends service to shutdown.
-        */
+         * Shut down the Friends Service.
+         *
+         * You probably shouldn't use this. It causes the whole daemon
+         * to exit, preventing any other clients from accessing it.
+         *
+         * @since 0.1
+         */
         public void quit()
         {
             try {
@@ -102,10 +93,10 @@
         }
 
         /**
-            refresh:
-
-            Tells the friends service to perform a refresh.
-        */
+         * Perform a refresh of all enabled accounts.
+         *
+         * @since 0.1
+         */
         public void refresh()
         {
             try {
@@ -116,11 +107,18 @@
         }
 
         /**
-            do:
-            @action: The action (like, unlike, retweet)
-            @account_id: The account to post from
-            @message_id: The friends message ID
-        */
+         * Perform any arbitrary action on an individual account. This
+         * is the primary interface for triggering likes, unlikes,
+         * etc.
+         *
+         * @param action The action to perform, such as 'like',
+         * 'unlike', 'retweet', etc.
+         * @param account_id The {@link Ag.Account.id} to post from.
+         * @param message_id The ID of the message to be liked/unliked/etc.
+         *
+         * @since 0.1
+         * @see features
+         */
         public bool do(string action, string account_id, string message_id)
         {
             try {
@@ -134,13 +132,17 @@
         }
 
        /**
-        * Upload an image to the specified account_id
-        *
-        * @param account_id The {@link Ag.Account.id} to post from
-        * @param uri local or remote URI to a file to upload
-        * @param description description to include in the post
-        *
-        * @since 0.1 
+        * Upload an image to the specified account_id.
+        *
+        * Currently this is only supported on Facebook, but we plan to
+        * support other protocols soon.
+        *
+        * @param account_id The {@link Ag.Account.id} to post from.
+        * @param uri Local or remote URI of a file to upload.
+        * @param description Description or caption to include for the
+        * uploaded photo.
+        *
+        * @since 0.1
         */
         public bool upload(string account_id, string uri, string description)
         {
@@ -157,13 +159,15 @@
        /**
         * Upload an image to the specified account_id, asynchronously.
         *
-        * @param account_id The {@link Ag.Account.id} to post from
-        * @param uri local or remote URI to a file 
-        * @param description description to include in the post
-        * @param result_url URL returned in the upload
-        * 
-        * @since 0.1 
-        * @throws GLib.IOError if uploading the image failed
+        * @param account_id The {@link Ag.Account.id} to post from.
+        * @param uri Local or remote URI of a file to upload.
+        * @param description Description or caption to include for the
+        * uploaded photo.
+        * @param result_url The destintion URL of the successfully
+        * uploaded file.
+        *
+        * @since 0.1
+        * @throws GLib.IOError if uploading the image failed.
         */
         public async bool upload_async(string account_id, string uri, string description, out string result_url) throws IOError
         {
@@ -179,13 +183,20 @@
 
 
         /**
-            send_reply:
-            @message: The message to post to Friends
-            @account_id: The account to post from
-            @message_id: The friends message ID
-
-            Reply or comment on a post 
-        */
+         * Reply to an existing message.
+         *
+         * Note that twitter will require you to @mention the name of
+         * the person you are replying to in order for it to appear
+         * correctly as a reply. Otherwise, the message will post
+         * successfully but it will simply appear as a normal message,
+         * without any conversation threading.
+         *
+         * @param message The text of the reply that you want to send.
+         * @param account_id The {@link Ag.Account.id} to post from.
+         * @param message_id The ID of the message that you are replying to.
+         *
+         * @since 0.1
+         */
         public bool send_reply(string message, string account_id, string message_id)
         {
             try {
@@ -200,12 +211,13 @@
 
 
         /**
-            send_message:
-            @account_id: The account_id to use or null
-            @message: The message to post to Friends
-
-            Posts a message
-        */
+         * Write a public message to the specified account.
+         *
+         * @param account_id The {@link Ag.Account.id} to post from.
+         * @param message The text of the message to post publicly.
+         *
+         * @since 0.1
+         */
         public bool send_message(string? account_id, string message)
         {
             try {
@@ -221,6 +233,20 @@
             return false;
         }
 
+        /**
+         * This method returns a list of all the possible actions
+         * supported by a given protocol. This can be used to
+         * determine what actions can be triggered by the ``do``
+         * method, although do is not capable of triggering all
+         * methods returned by this function. Anything that ``do`` isn't
+         * capable of will have it's own special method for invoking.
+         *
+         * @param protocol One of ``facebook``, ``flickr``,
+         * ``foursquare``, ``identica``, or ``twitter``.
+         *
+         * @since 0.1
+         * @see do
+         */
         public string[] features(string protocol)
         {
             string[] _features = null;
@@ -234,13 +260,13 @@
                 warning(e.message);
             }
             return _features;
-	}
+        }
 
         /**
-            version:
-
-            Return value: the version of the Gwibber service that is running.
-        */
+         * Identify the version of Friends Service that is running.
+         *
+         * @since 0.1
+         */
         public string version()
         {
             try {
@@ -251,6 +277,11 @@
             return "";
         }
 
+        /**
+         * Clear all notifications from the messaging menu.
+         *
+         * @since 0.1
+         */
         public void messaging_menu_clear()
         {
              try {

=== modified file 'src/urlshorten.vala'
--- src/urlshorten.vala	2012-12-10 20:46:09 +0000
+++ src/urlshorten.vala	2013-01-05 00:43:20 +0000
@@ -48,8 +48,12 @@
 
 
         /**
-         * com.Friends.URLShorten
-         **/
+         * Pass any URL to this method and it will shorten it for you.
+         *
+         * @param url The long URL you need shortened.
+         *
+         * @since 0.1
+         */
         public string shorten(string url)
         {
             try
@@ -61,6 +65,6 @@
                 warning (e.message);
                 return "Failed";
             }
-        }   
+        }
     }
 }

=== modified file 'src/utils.vala'
--- src/utils.vala	2012-12-10 19:21:22 +0000
+++ src/utils.vala	2013-01-05 00:43:20 +0000
@@ -27,9 +27,9 @@
         }
 
         /**
-            create_time_string:
-            @time: The timestamp as a string
-        */
+         * Convert the timestamp into a string ending in 'ago'.
+         * @param time The timestamp as a string.
+         */
         public string create_time_string(string t)
         {
             string nt = t + "ZZ";
@@ -50,6 +50,12 @@
             return ngettext("%i day ago", "%i days ago", (int) d/86400).printf(d/86400);
         }
 
+        /**
+         * Locally cache avatar URLs; if the given URL is already
+         * cached, then the path to the cached file is returned. If
+         * the file is missing from the cache, it attempts to download
+         * the file and cache it.
+         */
         public string? get_avatar_path(string url)
         {
             string _avatar_cache_image = Path.build_path (Path.DIR_SEPARATOR_S, Environment.get_user_cache_dir(), "friends/avatars", GLib.Checksum.compute_for_string (GLib.ChecksumType.SHA1, url));
@@ -60,7 +66,5 @@
             else
                 return null;
         }
-
     }
 }
-