[gtk+/treeview-refactor] docs: Move documentation to inline comments: GtkProgressBar

[Tristan Van Berkom <tvb src gnome org>]

commit a00a0fb20940c4e97e3f31b7c724c66b5ddcb180
Author: Patrick Bernaud <patrickb chez com>
Date:   Mon Nov 8 18:36:39 2010 +0100

    docs: Move documentation to inline comments: GtkProgressBar
    
    Fixes https://bugzilla.gnome.org/show_bug.cgi?id=634339
    
    Signed-off-by: Javier Jardón <jjardon gnome org>

 docs/reference/gtk/tmpl/.gitignore          |    1 +
 docs/reference/gtk/tmpl/gtkprogressbar.sgml |  241 ---------------------------
 gtk/gtkprogressbar.c                        |   35 ++++
 3 files changed, 36 insertions(+), 241 deletions(-)
---
diff --git a/docs/reference/gtk/tmpl/.gitignore b/docs/reference/gtk/tmpl/.gitignore
index 5ac6dc1..c1f7037 100644
--- a/docs/reference/gtk/tmpl/.gitignore
+++ b/docs/reference/gtk/tmpl/.gitignore
@@ -34,6 +34,7 @@ gtkpagesetup.sgml
 gtkpagesetupunixdialog.sgml
 gtkpapersize.sgml
 gtkprinter.sgml
+gtkprogressbar.sgml
 gtkradioaction.sgml
 gtkradiobutton.sgml
 gtkrange.sgml
diff --git a/gtk/gtkprogressbar.c b/gtk/gtkprogressbar.c
index 1caac5d..9cca76b 100644
--- a/gtk/gtkprogressbar.c
+++ b/gtk/gtkprogressbar.c
@@ -33,6 +33,34 @@
 #include "gtkprivate.h"
 #include "gtkintl.h"
 
+/**
+ * SECTION:gtkprogressbar
+ * @Short_description: A widget which indicates progress visually
+ * @Title: GtkProgressBar
+ *
+ * The #GtkProgressBar is typically used to display the progress of a long
+ * running operation.  It provides a visual clue that processing
+ * is underway.  The #GtkProgressBar can be used in two different
+ * modes: percentage mode and activity mode.
+ *
+ * When an application can determine how much work needs to take place
+ * (e.g. read a fixed number of bytes from a file) and can monitor its
+ * progress, it can use the #GtkProgressBar in percentage mode and the user
+ * sees a growing bar indicating the percentage of the work that has
+ * been completed.  In this mode, the application is required to call
+ * gtk_progress_bar_set_fraction() periodically to update the progress bar.
+ *
+ * When an application has no accurate way of knowing the amount of work
+ * to do, it can use the #GtkProgressBar in activity mode, which shows
+ * activity by a block moving back and forth within the progress area. In
+ * this mode, the application is required to call gtk_progress_bar_pulse()
+ * periodically to update the progress bar.
+ *
+ * There is quite a bit of flexibility provided to control the appearance
+ * of the #GtkProgressBar.  Functions are provided to control the
+ * orientation of the bar, optional text can be displayed along with
+ * the bar, and the step size used in activity mode can be set.
+ */
 
 #define MIN_HORIZONTAL_BAR_WIDTH   150
 #define MIN_HORIZONTAL_BAR_HEIGHT  20
@@ -356,6 +384,13 @@ gtk_progress_bar_get_property (GObject      *object,
     }
 }
 
+/**
+ * gtk_progress_bar_new:
+ *
+ * Creates a new #GtkProgressBar.
+ *
+ * Returns: a #GtkProgressBar.
+ */
 GtkWidget*
 gtk_progress_bar_new (void)
 {