[gnome-builder] doc: add docs for IdeBuildManager

[Christian Hergert <chergert src gnome org>]

commit 07b9fe3b2d836a680310e8a8b311650554b68139
Author: Christian Hergert <chergert redhat com>
Date:   Sat Nov 4 18:18:29 2017 -0700

    doc: add docs for IdeBuildManager

 src/libide/buildsystem/ide-build-manager.c |  144 +++++++++++++++++++++++++++-
 1 files changed, 142 insertions(+), 2 deletions(-)
---
diff --git a/src/libide/buildsystem/ide-build-manager.c b/src/libide/buildsystem/ide-build-manager.c
index 50a4517..bc59012 100644
--- a/src/libide/buildsystem/ide-build-manager.c
+++ b/src/libide/buildsystem/ide-build-manager.c
@@ -32,6 +32,26 @@
 #include "runtimes/ide-runtime.h"
 #include "runtimes/ide-runtime-manager.h"
 
+/**
+ * SECTION:ide-build-manager
+ * @title: IdeBuildManager
+ * @short_description: Manages the active build configuration and pipeline
+ *
+ * The #IdeBuildManager is responsible for managing the active build pipeline
+ * as well as providing common high-level actions to plugins.
+ *
+ * You can use various async operations such as
+ * ide_build_manager_execute_async(), ide_build_manager_clean_async(), or
+ * ide_build_manager_rebuild_async() to build, clean, and rebuild respectively
+ * without needing to track the build pipeline.
+ *
+ * The #IdeBuildPipeline is used to specify how and when build operations
+ * should occur. Plugins attach build stages to the pipeline to perform
+ * build actions.
+ *
+ * Since: 3.22
+ */
+
 struct _IdeBuildManager
 {
   IdeObject         parent_instance;
@@ -590,6 +610,8 @@ ide_build_manager_class_init (IdeBuildManagerClass *klass)
    *
    * This might be false if the required runtime is not available or other
    * errors in setting up the build pipeline.
+   *
+   * Since: 3.22
    */
   properties [PROP_CAN_BUILD] =
     g_param_spec_boolean ("can-build",
@@ -605,6 +627,8 @@ ide_build_manager_class_init (IdeBuildManagerClass *klass)
    * executing. This can be bound to UI elements to display to the
    * user that a build is active (and therefore other builds cannot
    * be activated at the moment).
+   *
+   * Since: 3.22
    */
   properties [PROP_BUSY] =
     g_param_spec_boolean ("busy",
@@ -613,6 +637,13 @@ ide_build_manager_class_init (IdeBuildManagerClass *klass)
                           FALSE,
                           G_PARAM_READABLE | G_PARAM_STATIC_STRINGS);
 
+  /**
+   * IdeBuildManager:error-count:
+   *
+   * The number of errors discovered during the build process.
+   *
+   * Since: 3.22
+   */
   properties [PROP_ERROR_COUNT] =
     g_param_spec_uint ("error-count",
                        "Error Count",
@@ -625,6 +656,8 @@ ide_build_manager_class_init (IdeBuildManagerClass *klass)
    *
    * The "has-diagnostics" property indicates that there have been
    * diagnostics found during the last execution of the build pipeline.
+   *
+   * Since: 3.22
    */
   properties [PROP_HAS_DIAGNOSTICS] =
     g_param_spec_boolean ("has-diagnostics",
@@ -638,6 +671,8 @@ ide_build_manager_class_init (IdeBuildManagerClass *klass)
    *
    * The "last-build-time" property contains a #GDateTime of the time
    * the last build request was submitted.
+   *
+   * Since: 3.22
    */
   properties [PROP_LAST_BUILD_TIME] =
     g_param_spec_boxed ("last-build-time",
@@ -652,6 +687,8 @@ ide_build_manager_class_init (IdeBuildManagerClass *klass)
    * The "message" property contains a string message describing
    * the current state of the build process. This may be bound to
    * UI elements to notify the user of the buid progress.
+   *
+   * Since: 3.22
    */
   properties [PROP_MESSAGE] =
     g_param_spec_string ("message",
@@ -660,6 +697,14 @@ ide_build_manager_class_init (IdeBuildManagerClass *klass)
                          NULL,
                          G_PARAM_READABLE | G_PARAM_STATIC_STRINGS);
 
+  /**
+   * IdeBuildManager:pipeline:
+   *
+   * The "pipeline" property is the build pipeline that the build manager
+   * is currently managing.
+   *
+   * Since: 3.22
+   */
   properties [PROP_PIPELINE] =
     g_param_spec_object ("pipeline",
                          "Pipeline",
@@ -678,6 +723,8 @@ ide_build_manager_class_init (IdeBuildManagerClass *klass)
    * The value of this property is a #GTimeSpan, which are 64-bit signed
    * integers with microsecond precision. See %G_USEC_PER_SEC for a constant
    * to tranform this to seconds.
+   *
+   * Since: 3.22
    */
   properties [PROP_RUNNING_TIME] =
     g_param_spec_int64 ("running-time",
@@ -688,6 +735,14 @@ ide_build_manager_class_init (IdeBuildManagerClass *klass)
                         0,
                         G_PARAM_READABLE | G_PARAM_STATIC_STRINGS);
 
+  /**
+   * IdeBuildManager:warning-count:
+   *
+   * The "warning-count" property contains the number of warnings that have
+   * been discovered in the current build request.
+   *
+   * Since: 3.22
+   */
   properties [PROP_WARNING_COUNT] =
     g_param_spec_uint ("warning-count",
                        "Warning Count",
@@ -705,6 +760,8 @@ ide_build_manager_class_init (IdeBuildManagerClass *klass)
    * The "build-started" signal is emitted when a new build has started.
    * The build may be an incremental build. The @pipeline instance is
    * the build pipeline which is being executed.
+   *
+   * Since: 3.22
    */
   signals [BUILD_STARTED] =
     g_signal_new_class_handler ("build-started",
@@ -726,6 +783,8 @@ ide_build_manager_class_init (IdeBuildManagerClass *klass)
    *
    * Contrast this with #IdeBuildManager::build-finished for a successful
    * build.
+   *
+   * Since: 3.22
    */
   signals [BUILD_FAILED] =
     g_signal_new_class_handler ("build-failed",
@@ -743,6 +802,8 @@ ide_build_manager_class_init (IdeBuildManagerClass *klass)
    *
    * The "build-finished" signal is emitted when a build completed
    * successfully.
+   *
+   * Since: 3.22
    */
   signals [BUILD_FINISHED] =
     g_signal_new_class_handler ("build-finished",
@@ -879,10 +940,11 @@ ide_build_manager_init (IdeBuildManager *self)
  * ide_build_manager_get_busy:
  * @self: An #IdeBuildManager
  *
- * Gets if the #IdeBuildManager is currently busy building the
- * project.
+ * Gets if the #IdeBuildManager is currently busy building the project.
  *
  * See #IdeBuildManager:busy for more information.
+ *
+ * Since: 3.22
  */
 gboolean
 ide_build_manager_get_busy (IdeBuildManager *self)
@@ -904,6 +966,8 @@ ide_build_manager_get_busy (IdeBuildManager *self)
  * See #IdeBuildManager:message for more information.
  *
  * Returns: (transfer full): A string containing the build message or %NULL
+ *
+ * Since: 3.22
  */
 gchar *
 ide_build_manager_get_message (IdeBuildManager *self)
@@ -926,6 +990,8 @@ ide_build_manager_get_message (IdeBuildManager *self)
  * See #IdeBuildManager:last-build-time for more information.
  *
  * Returns: (nullable) (transfer none): A #GDateTime or %NULL.
+ *
+ * Since: 3.22
  */
 GDateTime *
 ide_build_manager_get_last_build_time (IdeBuildManager *self)
@@ -942,6 +1008,8 @@ ide_build_manager_get_last_build_time (IdeBuildManager *self)
  * #GTimeSpan.
  *
  * Returns: A #GTimeSpan containing the elapsed time of the build.
+ *
+ * Since: 3.22
  */
 GTimeSpan
 ide_build_manager_get_running_time (IdeBuildManager *self)
@@ -962,6 +1030,8 @@ ide_build_manager_get_running_time (IdeBuildManager *self)
  *
  * You may also activate this using the "cancel" #GAction provided
  * by the #GActionGroup interface.
+ *
+ * Since: 3.22
  */
 void
 ide_build_manager_cancel (IdeBuildManager *self)
@@ -990,6 +1060,8 @@ ide_build_manager_cancel (IdeBuildManager *self)
  * reloaded as build configurations change.
  *
  * Returns: (transfer none) (nullable): An #IdeBuildPipeline.
+ *
+ * Since: 3.22
  */
 IdeBuildPipeline *
 ide_build_manager_get_pipeline (IdeBuildManager *self)
@@ -1082,6 +1154,8 @@ ide_build_manager_save_all_cb (GObject      *object,
  * build pipeline and execute a build. Upon completion, @callback will be
  * executed and it can determine the success or failure of the operation
  * using ide_build_manager_execute_finish().
+ *
+ * Since: 3.22
  */
 void
 ide_build_manager_execute_async (IdeBuildManager     *self,
@@ -1180,6 +1254,8 @@ ide_build_manager_execute_async (IdeBuildManager     *self,
  * Completes a request to ide_build_manager_execute_async().
  *
  * Returns: %TRUE if successful, otherwise %FALSE and @error is set.
+ *
+ * Since: 3.22
  */
 gboolean
 ide_build_manager_execute_finish (IdeBuildManager  *self,
@@ -1223,6 +1299,20 @@ ide_build_manager_clean_cb (GObject      *object,
     g_task_return_boolean (task, TRUE);
 }
 
+/**
+ * ide_build_manager_clean_async:
+ * @self: a #IdeBuildManager
+ * @phase: the build phase to clean
+ * @cancellable: (nullable): A #GCancellable or %NULL
+ * @callback: (nullable): a callback to execute upon completion, or %NULL
+ * @user_data: closure data for @callback
+ *
+ * Asynchronously requests that the build pipeline clean up to @phase.
+ *
+ * See ide_build_pipeline_clean_async() for more information.
+ *
+ * Since: 3.22
+ */
 void
 ide_build_manager_clean_async (IdeBuildManager     *self,
                                IdeBuildPhase        phase,
@@ -1272,6 +1362,18 @@ ide_build_manager_clean_async (IdeBuildManager     *self,
   IDE_EXIT;
 }
 
+/**
+ * ide_build_manager_clean_finish:
+ * @self: a #IdeBuildManager
+ * @result: A #GAsyncResult
+ * @error: a location for a #GError, or %NULL
+ *
+ * Completes an asynchronous request to ide_build_manager_clean_async().
+ *
+ * Returns: %TRUE if successful; otherwise %FALSE and @error is set.
+ *
+ * Since: 3.22
+ */
 gboolean
 ide_build_manager_clean_finish (IdeBuildManager  *self,
                                 GAsyncResult     *result,
@@ -1312,6 +1414,22 @@ ide_build_manager_rebuild_cb (GObject      *object,
   IDE_EXIT;
 }
 
+/**
+ * ide_build_manager_rebuild_async:
+ * @self: a #IdeBuildManager
+ * @phase: the build phase to rebuild to
+ * @cancellable: (nullable): A #GCancellable or %NULL
+ * @callback: (nullable): a callback to execute upon completion, or %NULL
+ * @user_data: closure data for @callback
+ *
+ * Asynchronously requests that the build pipeline clean and rebuild up
+ * to the given phase. This may involve discarding previous build artifacts
+ * to allow for the rebuild process.
+ *
+ * See ide_build_pipeline_rebuild_async() for more information.
+ *
+ * Since: 3.22
+ */
 void
 ide_build_manager_rebuild_async (IdeBuildManager     *self,
                                  IdeBuildPhase        phase,
@@ -1353,6 +1471,18 @@ ide_build_manager_rebuild_async (IdeBuildManager     *self,
   IDE_EXIT;
 }
 
+/**
+ * ide_build_manager_rebuild_finish:
+ * @self: a #IdeBuildManager
+ * @result: A #GAsyncResult
+ * @error: a location for a #GError, or %NULL
+ *
+ * Completes an asynchronous request to ide_build_manager_rebuild_async().
+ *
+ * Returns: %TRUE if successful; otherwise %FALSE and @error is set.
+ *
+ * Since: 3.22
+ */
 gboolean
 ide_build_manager_rebuild_finish (IdeBuildManager  *self,
                                   GAsyncResult     *result,
@@ -1370,6 +1500,16 @@ ide_build_manager_rebuild_finish (IdeBuildManager  *self,
   IDE_RETURN (ret);
 }
 
+/**
+ * ide_build_manager_get_can_build:
+ * @self: a #IdeBuildManager
+ *
+ * Checks if the current pipeline is ready to build.
+ *
+ * Returns: %TRUE if a build operation can advance the pipeline.
+ *
+ * Since: 3.22
+ */
 gboolean
 ide_build_manager_get_can_build (IdeBuildManager *self)
 {