added missing documentation for GtkExperimentTranscript API methods

3 files changed, 99 insertions, 3 deletions

diff --git a/lib/gtk-experiment-widgets/gtk-experiment-transcript-formats.c b/lib/gtk-experiment-widgets/gtk-experiment-transcript-formats.c
index 4e4acfa..f2167e2 100644
--- a/lib/gtk-experiment-widgets/gtk-experiment-transcript-formats.c
+++ b/lib/gtk-experiment-widgets/gtk-experiment-transcript-formats.c
@@ -159,6 +159,21 @@ gtk_experiment_transcript_free_formats(GSList *formats)
  * API
  */
 
+/**
+ * @brief Load a format file to use with the transcript widget
+ *
+ * Loading a format file applies additional formattings (highlighting) to the
+ * transcript's contributions according to the rules specified in the file.
+ * For information about the format file syntax and semantics, refer to the
+ * "Experiment Player" manual.
+ *
+ * The format file is parsed and and compiled to an internal representation.
+ *
+ * @param trans    Widget instance
+ * @param filename File name of format file to load (\c NULL or empty string
+ *                 resets any formattings of a previously loaded file)
+ * @return \c TRUE on error, else \c FALSE
+ */
 /** @todo report errors using GError */
 gboolean
 gtk_experiment_transcript_load_formats(GtkExperimentTranscript *trans,
@@ -215,6 +230,28 @@ redraw:
 	return res;
 }
 
+/**
+ * @brief Specify an interactive format string for a transcript widget
+ *
+ * Associates a single format rule with a transcript widget. The formatting
+ * changes are cumulatively applied after any changes introduced by a format
+ * file loaded into the widget. The interactive format rule is independant of
+ * any format file rules, that is it is not reset when format file rules are
+ * reset.
+ * A rule may also be given without Pango markup (plain regular expression),
+ * applying default formattings for that regular expression. Default formattings
+ * may be configured via public instance attributes of the widget.
+ * For information about the format rule syntax and semantics, refer to the
+ * "Experiment Player" manual.
+ *
+ * @sa gtk_experiment_transcript_load_formats
+ *
+ * @param trans       Widget instance
+ * @param format_str  Format rule string (with or without markup)
+ * @param with_markup Must be \c TRUE if the format_str contains Pango markup,
+ *                    else \c FALSE
+ * @return \c TRUE on error, else \c FALSE
+ */
 gboolean
 gtk_experiment_transcript_set_interactive_format(GtkExperimentTranscript *trans,
 						 const gchar *format_str,
diff --git a/lib/gtk-experiment-widgets/gtk-experiment-transcript.c b/lib/gtk-experiment-widgets/gtk-experiment-transcript.c
index cd5d316..d5b957c 100644
--- a/lib/gtk-experiment-widgets/gtk-experiment-transcript.c
+++ b/lib/gtk-experiment-widgets/gtk-experiment-transcript.c
@@ -676,6 +676,17 @@ gtk_experiment_transcript_new(const gchar *speaker)
 	return GTK_WIDGET(trans);
 }
 
+/**
+ * @brief Load contributions from an experiment transcript file.
+ *
+ * The transcript file is given as an \e ExperimentReader object instance.
+ * Only contributions (every text fragment identified by a timepoint) of the
+ * configured speaker are used.
+ *
+ * @param trans Widget instance
+ * @param exp   \e ExperimentReader instance
+ * @return \c TRUE on error, else \c FALSE
+ */
 gboolean
 gtk_experiment_transcript_load(GtkExperimentTranscript *trans,
 			       ExperimentReader *exp)
@@ -689,6 +700,19 @@ gtk_experiment_transcript_load(GtkExperimentTranscript *trans,
 	return trans->priv->contribs == NULL;
 }
 
+/**
+ * @brief Load contributions from an experiment transcript file.
+ *
+ * The transcript file is given as a file name.
+ * Only contributions (every text fragment identified by a timepoint) of the
+ * configured speaker are used.
+ *
+ * @sa gtk_experiment_transcript_load
+ *
+ * @param trans    Widget instance
+ * @param filename \e ExperimentReader instance
+ * @return \c TRUE on error, else \c FALSE
+ */
 gboolean
 gtk_experiment_transcript_load_filename(GtkExperimentTranscript *trans,
 					const gchar *filename)
@@ -704,6 +728,14 @@ gtk_experiment_transcript_load_filename(GtkExperimentTranscript *trans,
 	return res;
 }
 
+/**
+ * @brief Set alignment (justification) of text blocks in a transcript widget
+ *
+ * The alignment defaults to \c PANGO_ALIGN_LEFT for new widget instances.
+ *
+ * @param trans     Widget instance
+ * @param alignment New text alignment
+ */
 void
 gtk_experiment_transcript_set_alignment(GtkExperimentTranscript *trans,
 					PangoAlignment alignment)
@@ -717,6 +749,14 @@ gtk_experiment_transcript_set_alignment(GtkExperimentTranscript *trans,
 					       cur_alignment == alignment);
 }
 
+/**
+ * @brief Get alignment (justification) of text blocks in a transcript widget
+ *
+ * @sa gtk_experiment_transcript_set_alignment
+ *
+ * @param trans Widget instance
+ * @return Current text alignment
+ */
 PangoAlignment
 gtk_experiment_transcript_get_alignment(GtkExperimentTranscript *trans)
 {
@@ -726,6 +766,19 @@ gtk_experiment_transcript_get_alignment(GtkExperimentTranscript *trans)
 	return pango_layout_get_alignment(trans->priv->layer_text_layout);
 }
 
+/**
+ * @brief Get time-adjustment currently used by a transcript widget
+ *
+ * The time-adjustment is the only way to control the portion of the transcript
+ * displayed by the widget.
+ * The adjustment's value is in milliseconds.
+ * The widget will initialize one on construction, so there \e should always be
+ * an adjustment to get.
+ *
+ * @param trans Widget instance
+ * @return Currently used time-adjustment
+ */
+
 GtkAdjustment *
 gtk_experiment_transcript_get_time_adjustment(GtkExperimentTranscript *trans)
 {
@@ -743,7 +796,7 @@ gtk_experiment_transcript_get_time_adjustment(GtkExperimentTranscript *trans)
  *
  * @sa gtk_experiment_transcript_get_time_adjustment
  *
- * @param trans \e GtkExperimentTranscript instance
+ * @param trans Widget instance
  * @param adj   New \e GtkAdjustment to use as time-adjustment.
  */
 void
diff --git a/lib/gtk-experiment-widgets/gtk-experiment-transcript.h b/lib/gtk-experiment-widgets/gtk-experiment-transcript.h
index fc73285..9d300b2 100644
--- a/lib/gtk-experiment-widgets/gtk-experiment-transcript.h
+++ b/lib/gtk-experiment-widgets/gtk-experiment-transcript.h
@@ -62,8 +62,14 @@ typedef struct _GtkExperimentTranscript {
 	GtkWidget parent_instance;		/**< Parent instance structure */
 
 	gchar *speaker;				/**< Name of speaker whose contributions are displayed (\b read-only) */
-	gboolean reverse;			/**< Reverse mode (\b read-write) */
-
+	gboolean reverse;			/**< Reverse mode activated (\b read-only) */
+
+	/**
+	 * Default formattings to apply for interactive for interactive format
+	 * rules if no Pango markup is specified.
+	 * A \c NULL pointer means that the correspondig text property will not
+	 * be changed. After widget instantiation all fields are \c NULL.
+	 */
 	struct _GtkExperimentTranscriptInteractiveFormat {
 		PangoFontDescription *default_font;	/**< Default interactive format font */
 		GdkColor *default_text_color;		/**< Default interactive format text color */