[gitg/vala] Added documentation for some interfaces

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

commit 6c18f5e6ace3f27aa709dfc8e40b0882ae4e8881
Author: Jesse van den Kieboom <jesse vandenkieboom epfl ch>
Date:   Tue Jul 17 09:45:15 2012 +0200

    Added documentation for some interfaces

 libgitg-ext/gitg-ext-application.vala |   45 +++++++++++++++++++++++++++++++++
 libgitg-ext/gitg-ext-panel.vala       |   15 +++++++++++
 libgitg-ext/gitg-ext-view.vala        |   12 ++++++---
 3 files changed, 68 insertions(+), 4 deletions(-)
---
diff --git a/libgitg-ext/gitg-ext-application.vala b/libgitg-ext/gitg-ext-application.vala
index c3a4fa0..932a33a 100644
--- a/libgitg-ext/gitg-ext-application.vala
+++ b/libgitg-ext/gitg-ext-application.vala
@@ -20,16 +20,61 @@
 namespace GitgExt
 {
 
+/**
+ * Application is an interface to access the main gitg application.
+ *
+ * The application interface is provided to plugins to access the main gitg
+ * application instance. It contains properties to access the currently open
+ * repository as well as methods to open or create repositories.
+ *
+ **/
 public interface Application : Object
 {
+	/**
+	 * The currently open repository.
+	 */
 	public abstract Gitg.Repository? repository { owned get; }
+
+	/**
+	 * A application wide message bus over which plugins can communicate.
+	 */
 	public abstract GitgExt.MessageBus message_bus { owned get; }
+
+	/**
+	 * The current application main view.
+	 */
 	public abstract GitgExt.View? current_view { owned get; }
 
+	/**
+	 * Set the current application main view.
+	 *
+	 * @param id the id of the view { link View.id}.
+	 *
+	 * @return the created new main view, or ``null`` if no view with the
+	 *         given id exists.
+	 */
 	public abstract GitgExt.View? view(string id);
 
+	/**
+	 * Open an existing repository.
+	 *
+	 * @param repository the path to the repository to open.
+	 *
+	 */
 	public abstract void open(File repository);
+
+	/**
+	 * Create and open a new repository.
+	 *
+	 * @param repository the path at which the new repository is to be created.
+	 *
+	 */
 	public abstract void create(File repository);
+
+	/**
+	 * Close the currently open repository.
+	 *
+	 **/
 	public abstract void close();
 }
 
diff --git a/libgitg-ext/gitg-ext-panel.vala b/libgitg-ext/gitg-ext-panel.vala
index 55ce349..b0f0db8 100644
--- a/libgitg-ext/gitg-ext-panel.vala
+++ b/libgitg-ext/gitg-ext-panel.vala
@@ -21,6 +21,21 @@ namespace GitgExt
 {
 
 public interface Panel : Object
+/**
+ * Panel interfaces implemented to show additional details of a particular view.
+ *
+ * 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
+ * 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
+ * displayed when the panel is activated.
+ *
+ */
 {
 	public abstract Application? application { owned get; construct; }
 
diff --git a/libgitg-ext/gitg-ext-view.vala b/libgitg-ext/gitg-ext-view.vala
index c3a5429..5568f5d 100644
--- a/libgitg-ext/gitg-ext-view.vala
+++ b/libgitg-ext/gitg-ext-view.vala
@@ -54,7 +54,6 @@ public enum ViewAction
  * automatically in the gitg interface according to the various interface
  * methods and properties that need to be implemented.
  *
- * == Default View Navigation ==
  * To provide a default navigation when the view is active, the
  * #GitgExtView::navigation property should be implemented and should return a
  * non-null #GitgExtNavigation. This navigation section will always be present
@@ -97,7 +96,9 @@ public interface View : Object
 	public abstract Gtk.Widget? widget { owned get; }
 
 	/**
-	 * Main navigation for the view. When provided, the corresponding navigation
+	 * Main navigation for the view.
+	 *
+	 * When provided, the corresponding navigation
 	 * section will be added in the navigation panel when the view is activated.
 	 */
 	public abstract Navigation? navigation { owned get; }
@@ -114,14 +115,17 @@ public interface View : Object
 	public abstract bool is_available();
 
 	/**
-	 * @param action the action
+	 * Check whether the view is the default view for a particular action.
 	 *
 	 * Implement this method when a view should be the preferred default view
 	 * for a particular action. The first available view indicating to be
 	 * a default view will be used as the default activated view when launching
 	 * gitg (or when opening a repository).
 	 *
-	 * @return %TRUE if the view is a default for @action, %FALSE otherwise.
+	 * @param action the action
+	 *
+	 * @return ``true`` if the view is a default for @action, ``false`` otherwise.
+	 *
 	 */
 	public abstract bool is_default_for(ViewAction action);
 }