[gnome-builder/wip/libide: 150/237] libide: add missing annotations to calm introspection

[Christian Hergert <chergert src gnome org>]

commit 2ca29ebd822a1d82c37d82757f7b2ed4e407b5fa
Author: Christian Hergert <christian hergert me>
Date:   Thu Feb 12 14:47:44 2015 -0800

    libide: add missing annotations to calm introspection

 libide/clang/ide-clang-service.c |    8 ++++++++
 libide/git/ide-git-vcs.c         |    7 +++++++
 libide/ide-back-forward-list.c   |   11 +++++++++++
 libide/ide-builder.c             |    7 +++++++
 libide/ide-context.c             |   23 +++++++++++++++++++++++
 libide/ide-device-provider.c     |    8 ++++++++
 libide/ide-file.c                |   15 +++++++++++++++
 libide/ide-project-file.c        |   15 +++++++++++++++
 libide/ide-project-files.c       |    8 ++++++++
 libide/ide-project-item.c        |    9 +++++++++
 libide/ide-project.c             |   16 ++++++++++++++++
 11 files changed, 127 insertions(+), 0 deletions(-)
---
diff --git a/libide/clang/ide-clang-service.c b/libide/clang/ide-clang-service.c
index 2e0d6a8..5009561 100644
--- a/libide/clang/ide-clang-service.c
+++ b/libide/clang/ide-clang-service.c
@@ -250,6 +250,14 @@ ide_clang_service_get_translation_unit_async (IdeClangService     *self,
   g_task_run_in_thread (task, ide_clang_service_parse_worker);
 }
 
+/**
+ * ide_clang_service_get_translation_unit_finish:
+ *
+ * Completes an asychronous request to get a translation unit for a given file.
+ * See ide_clang_service_get_translation_unit_async() for more information.
+ *
+ * Returns: (transfer full): An #IdeClangTranslationUnit or %NULL up on failure.
+ */
 IdeClangTranslationUnit *
 ide_clang_service_get_translation_unit_finish (IdeClangService  *self,
                                                GAsyncResult     *result,
diff --git a/libide/git/ide-git-vcs.c b/libide/git/ide-git-vcs.c
index 50f394c..9d7477e 100644
--- a/libide/git/ide-git-vcs.c
+++ b/libide/git/ide-git-vcs.c
@@ -45,6 +45,13 @@ enum {
 
 static GParamSpec *gParamSpecs [LAST_PROP];
 
+/**
+ * ide_git_vcs_get_repository:
+ *
+ * Retrieves the underlying #GgitRepository used by @vcs.
+ *
+ * Returns: (transfer none): A #GgitRepository.
+ */
 GgitRepository *
 ide_git_vcs_get_repository (IdeGitVcs *vcs)
 {
diff --git a/libide/ide-back-forward-list.c b/libide/ide-back-forward-list.c
index 3d29b4f..3660443 100644
--- a/libide/ide-back-forward-list.c
+++ b/libide/ide-back-forward-list.c
@@ -211,6 +211,17 @@ ide_back_forward_list_push (IdeBackForwardList *self,
   g_return_if_fail (priv->backward->length > 0);
 }
 
+/**
+ * ide_back_forward_list_branch:
+ *
+ * Branches @self into a newly created #IdeBackForwardList.
+ *
+ * This can be used independently and then merged back into a global
+ * #IdeBackForwardList. This can be useful in situations where you have
+ * multiple sets of editors.
+ *
+ * Returns: (transfer full): An #IdeBackForwardList
+ */
 IdeBackForwardList *
 ide_back_forward_list_branch (IdeBackForwardList *self)
 {
diff --git a/libide/ide-builder.c b/libide/ide-builder.c
index 3378bf5..60c05c5 100644
--- a/libide/ide-builder.c
+++ b/libide/ide-builder.c
@@ -67,6 +67,13 @@ ide_builder_build_async (IdeBuilder           *builder,
                            _("No implementation of build_async()"));
 }
 
+/**
+ * ide_builder_build_finish:
+ *
+ * Completes an asynchronous request to build the project.
+ *
+ * Returns: (transfer full): An #IdeBuildResult or %NULL upon failure.
+ */
 IdeBuildResult *
 ide_builder_build_finish (IdeBuilder    *builder,
                           GAsyncResult  *result,
diff --git a/libide/ide-context.c b/libide/ide-context.c
index 45eef62..704ffdc 100644
--- a/libide/ide-context.c
+++ b/libide/ide-context.c
@@ -190,6 +190,14 @@ ide_context_get_unsaved_files (IdeContext *context)
   return priv->unsaved_files;
 }
 
+/**
+ * ide_context_get_vcs:
+ *
+ * Retrieves the #IdeVcs used to load the project. If no version control system
+ * could be found, this will return an #IdeDirectoryVcs.
+ *
+ * Returns: (transfer none): An #IdeVcs.
+ */
 IdeVcs *
 ide_context_get_vcs (IdeContext *context)
 {
@@ -255,6 +263,13 @@ ide_context_new_finish (GAsyncResult  *result,
   return g_task_propagate_pointer (task, error);
 }
 
+/**
+ * ide_context_get_project:
+ *
+ * Retrieves the #IdeProject for the context.
+ *
+ * Returns: (transfer none): An #IdeContext.
+ */
 IdeProject *
 ide_context_get_project (IdeContext *context)
 {
@@ -265,6 +280,14 @@ ide_context_get_project (IdeContext *context)
   return priv->project;
 }
 
+/**
+ * ide_context_get_project_file:
+ *
+ * Retrieves a #GFile containing the project file that was used to load
+ * the context.
+ *
+ * Returns: (transfer none): A #GFile.
+ */
 GFile *
 ide_context_get_project_file (IdeContext *context)
 {
diff --git a/libide/ide-device-provider.c b/libide/ide-device-provider.c
index b3f20bc..7332f6b 100644
--- a/libide/ide-device-provider.c
+++ b/libide/ide-device-provider.c
@@ -53,6 +53,14 @@ ide_device_provider_get_settled (IdeDeviceProvider *provider)
   return TRUE;
 }
 
+/**
+ * ide_device_provider_get_devices:
+ *
+ * Retrieves a list of devices currently managed by @provider.
+ *
+ * Returns: (transfer none) (element-type IdeDevice*): A #GPtrArray of
+ *  #IdeDevice instances.
+ */
 GPtrArray *
 ide_device_provider_get_devices (IdeDeviceProvider *provider)
 {
diff --git a/libide/ide-file.c b/libide/ide-file.c
index 737c72f..2c02957 100644
--- a/libide/ide-file.c
+++ b/libide/ide-file.c
@@ -148,6 +148,14 @@ ide_file_create_language (IdeFile *self)
     }
 }
 
+/**
+ * ide_file_get_language:
+ *
+ * Retrieves the #IdeLanguage that was discovered for the file. In some cases,
+ * this will be a subclass of #IdeLanguage, such as #IdeCLanguage.
+ *
+ * Returns: (transfer none): An #IdeLanguage
+ */
 IdeLanguage *
 ide_file_get_language (IdeFile *self)
 {
@@ -161,6 +169,13 @@ ide_file_get_language (IdeFile *self)
   return priv->language;
 }
 
+/**
+ * ide_file_get_file:
+ *
+ * Retrieves the underlying #GFile represented by @self.
+ *
+ * Returns: (transfer none): A #GFile.
+ */
 GFile *
 ide_file_get_file (IdeFile *self)
 {
diff --git a/libide/ide-project-file.c b/libide/ide-project-file.c
index d964f04..e608492 100644
--- a/libide/ide-project-file.c
+++ b/libide/ide-project-file.c
@@ -49,6 +49,13 @@ ide_project_file_get_name (IdeProjectFile *self)
   return g_file_info_get_name (priv->file_info);
 }
 
+/**
+ * ide_project_file_get_file:
+ *
+ * Retrieves the underlying #GFile represented by @file.
+ *
+ * Returns: (transfer none): Retrieves the #GFile represented by @file.
+ */
 GFile *
 ide_project_file_get_file (IdeProjectFile *file)
 {
@@ -72,6 +79,14 @@ ide_project_file_set_file (IdeProjectFile *self,
     g_object_notify_by_pspec (G_OBJECT (self), gParamSpecs [PROP_FILE]);
 }
 
+/**
+ * ide_project_file_get_file_info:
+ *
+ * Retrieves a #GFileInfo containing the basic information about @file. This
+ * includes the name, display name, and file type.
+ *
+ * Returns: (transfer none): A #GFileInfo
+ */
 GFileInfo *
 ide_project_file_get_file_info (IdeProjectFile *file)
 {
diff --git a/libide/ide-project-files.c b/libide/ide-project-files.c
index 79e8246..5c9949e 100644
--- a/libide/ide-project-files.c
+++ b/libide/ide-project-files.c
@@ -88,6 +88,14 @@ ide_project_files_find_child (IdeProjectItem *item,
   return NULL;
 }
 
+/**
+ * ide_project_files_get_file_for_path:
+ *
+ * Retrieves an #IdeFile for the path. If no such path exists within the
+ * project, %NULL is returned.
+ *
+ * Returns: (transfer full) (nullable): An #IdeFile or %NULL.
+ */
 IdeFile *
 ide_project_files_get_file_for_path (IdeProjectFiles *self,
                                      const gchar     *path)
diff --git a/libide/ide-project-item.c b/libide/ide-project-item.c
index 66f236d..57f19ae 100644
--- a/libide/ide-project-item.c
+++ b/libide/ide-project-item.c
@@ -76,6 +76,15 @@ ide_project_item_get_children (IdeProjectItem *item)
   return priv->children;
 }
 
+/**
+ * ide_project_item_get_parent:
+ *
+ * Retrieves the parent #IdeProjectItem of @item, or %NULL if @item is the root
+ * of the project tree.
+ *
+ * Returns: (transfer none) (nullable): An #IdeProjectItem or %NULL if the item
+ *   is the root of the tree.
+ */
 IdeProjectItem *
 ide_project_item_get_parent (IdeProjectItem *item)
 {
diff --git a/libide/ide-project.c b/libide/ide-project.c
index e607f5e..88e53da 100644
--- a/libide/ide-project.c
+++ b/libide/ide-project.c
@@ -65,6 +65,13 @@ ide_project_set_name (IdeProject  *project,
     }
 }
 
+/**
+ * ide_project_get_root:
+ *
+ * Retrieves the root item of the project tree.
+ *
+ * Returns: (transfer none): An #IdeProjectItem
+ */
 IdeProjectItem *
 ide_project_get_root (IdeProject *project)
 {
@@ -100,6 +107,15 @@ ide_project_set_root (IdeProject     *project,
     g_object_notify_by_pspec (G_OBJECT (project), gParamSpecs [PROP_ROOT]);
 }
 
+/**
+ * ide_project_get_file_for_path:
+ *
+ * Retrieves an #IdeFile for the path specified. #IdeFile provides access to
+ * language specific features via ide_file_get_language().
+ *
+ * Returns: (transfer full) (nullable): An #IdeFile or %NULL if no matching
+ *   file could be found.
+ */
 IdeFile *
 ide_project_get_file_for_path (IdeProject  *self,
                                const gchar *path)