[gitg] Update documentation

[Jesse van den Kieboom <jessevdk src gnome org>]

commit ea3c4bb8d5597d8e49957081595532d69f14ce3d
Author: Jesse van den Kieboom <jesse vandenkieboom epfl ch>
Date:   Tue Oct 30 11:05:37 2012 +0100

    Update documentation

 libgitg-ext/gitg-ext-application.vala |    6 +-
 libgitg-ext/gitg-ext-message-id.vala  |   85 +++++++++++++++++++++++++++++++++
 libgitg-ext/gitg-ext-panel.vala       |    4 +-
 libgitg-ext/gitg-ext-ui-element.vala  |    2 +-
 libgitg-ext/gitg-ext-view.vala        |    2 +-
 5 files changed, 92 insertions(+), 7 deletions(-)
---
diff --git a/libgitg-ext/gitg-ext-application.vala b/libgitg-ext/gitg-ext-application.vala
index 932a33a..dd6c91a 100644
--- a/libgitg-ext/gitg-ext-application.vala
+++ b/libgitg-ext/gitg-ext-application.vala
@@ -27,7 +27,7 @@ namespace GitgExt
  * application instance. It contains properties to access the currently open
  * repository as well as methods to open or create repositories.
  *
- **/
+ */
 public interface Application : Object
 {
 	/**
@@ -36,7 +36,7 @@ public interface Application : Object
 	public abstract Gitg.Repository? repository { owned get; }
 
 	/**
-	 * A application wide message bus over which plugins can communicate.
+	 * An application wide message bus over which plugins can communicate.
 	 */
 	public abstract GitgExt.MessageBus message_bus { owned get; }
 
@@ -48,7 +48,7 @@ public interface Application : Object
 	/**
 	 * Set the current application main view.
 	 *
-	 * @param id the id of the view { link View.id}.
+	 * @param id the id of the view { link UIElement.id}.
 	 *
 	 * @return the created new main view, or ``null`` if no view with the
 	 *         given id exists.
diff --git a/libgitg-ext/gitg-ext-message-id.vala b/libgitg-ext/gitg-ext-message-id.vala
index 973dc9d..91f58b2 100644
--- a/libgitg-ext/gitg-ext-message-id.vala
+++ b/libgitg-ext/gitg-ext-message-id.vala
@@ -20,36 +20,121 @@
 namespace GitgExt
 {
 
+/**
+ * Message identifier object.
+ *
+ * The message identifier object is used to identify messages sent over the
+ * MessageBus. The message identifier contains an object path and a method.
+ * Both are simple strings and combined describe the location of a message as
+ * a kind of method on an object.
+ *
+ * Valid object paths start with a forward slash and further path elements are
+ * seperated by more forward slashes. The first element needs to start with
+ * an alpha character (or underscore) while further characters can be
+ * alpha numeric or underscores. An example of a valid path is:
+ *
+ * /path/to/object
+ *
+ * Method names on the other hand do not have any restrictions.
+ *
+ */
 public class MessageId : Object
 {
+	/**
+	 * Message object path.
+	 */
 	public string object_path { construct set; get; }
+
+	/**
+	 * Message method.
+	 */
 	public string method { construct set; get; }
 
+	/**
+	 * Full id of the message.
+	 *
+	 * Get the full id of the message identifier. The full id is simply
+	 * <path>.<method>
+	 *
+	 */
 	public string id
 	{
 		owned get { return object_path + "." + method; }
 	}
 
+	/**
+	 * Message hash.
+	 *
+	 * Get a hash for the message identifier suitable for use in a hash table.
+	 * The hash is simply a string hash of the full id of the message identifier.
+	 *
+	 * @return the message identifier hash.
+	 *
+	 */
 	public uint hash()
 	{
 		return id.hash();
 	}
 
+	/**
+	 * Compare two messages for equality.
+	 *
+	 * Compare two messages. Two message identifiers are equal when they have
+	 * the same object path and the same method name.
+	 *
+	 * @param other the message identifier to compare to.
+	 *
+	 * @return true if the message identifiers are equal, false otherwise.
+	 *
+	 */
 	public bool equal(MessageId other)
 	{
 		return id == other.id;
 	}
 
+	/**
+	 * Construct message identifier with object path and method.
+	 *
+	 * Create a new message identifier object with the given object path and
+	 * method name.
+	 *
+	 * @param object_path the object path
+	 * @param method the method name
+	 *
+	 * @return a new message identifier.
+	 *
+	 */
 	public MessageId(string object_path, string method)
 	{
 		Object(object_path: object_path, method: method);
 	}
 
+	/**
+	 * Create a copy of the message identifier.
+	 *
+	 * Create an exact copy of the message identifier.
+	 *
+	 * @return a new message identifier.
+	 *
+	 */
 	public MessageId copy()
 	{
 		return new MessageId(object_path, method);
 	}
 
+	/**
+	 * Check whether an object path is a valid path.
+	 *
+	 * Check whether the given path is a valid object path. A valid object path
+	 * starts with a forward slash, followed by at least one alpha character,
+	 * or underscore. Further valid characters include alphanumeric characters,
+	 * underscores or path separators (forward slash).
+	 *
+	 * Example: /path/to/object
+	 *
+	 * @return true if the specified path is valid, false otherwise
+	 *
+	 */
 	public static bool valid_object_path(string path)
 	{
 		if (path == null)
diff --git a/libgitg-ext/gitg-ext-panel.vala b/libgitg-ext/gitg-ext-panel.vala
index 3fad7f1..8d3f312 100644
--- a/libgitg-ext/gitg-ext-panel.vala
+++ b/libgitg-ext/gitg-ext-panel.vala
@@ -25,13 +25,13 @@ namespace GitgExt
  *
  * The panel interface can be implemented to show additional details of a
  * { link View}. The panel will be shown in a split view below the main view
- * when activated. Panels should implement the { link is_available} method to
+ * when activated. Panels should implement the { link UIElement.available} property to
  * indicate for which state of the application the panel is active. This usually
  * involves checking which view is currently active using
  * { link Application.current_view}.
  *
  * Each panel should have a unique id, a display name and an icon which will
- * be used in the interface to activate the panel. The { link widget} is
+ * be used in the interface to activate the panel. The { link UIElement.widget} is
  * displayed when the panel is activated.
  *
  */
diff --git a/libgitg-ext/gitg-ext-ui-element.vala b/libgitg-ext/gitg-ext-ui-element.vala
index e815d14..865b2ca 100644
--- a/libgitg-ext/gitg-ext-ui-element.vala
+++ b/libgitg-ext/gitg-ext-ui-element.vala
@@ -104,7 +104,7 @@ public interface UIElement : Object
 	 * This method is used to determine the order in which elements need to
 	 * appear in the UI.
 	 *
-	 * @returns -1 if the element should appear before @other, 1 if the
+	 * @return -1 if the element should appear before @other, 1 if the
 	 *          element should appear after @other and 0 if the order is
 	 *          unimportant.
 	 *
diff --git a/libgitg-ext/gitg-ext-view.vala b/libgitg-ext/gitg-ext-view.vala
index 195bd96..cf6758a 100644
--- a/libgitg-ext/gitg-ext-view.vala
+++ b/libgitg-ext/gitg-ext-view.vala
@@ -46,7 +46,7 @@ public enum ViewAction
 /**
  * gitg View interface.
  *
- * The GitgExtView interface can be implemented to provide a main view in
+ * The View interface can be implemented to provide a main view in
  * gitg. An example of such views are the builtin Dashboard, History and
  * Commit views.
  *