validate: Enhance documentation

validate/docs/validate/gst-validate-docs.sgml

@@ -55,6 +55,7 @@
     <xi:include href="xml/validate.xml"/>
     <xi:include href="xml/gst-validate-runner.xml"/>
     <xi:include href="xml/gst-validate-scenario.xml"/>
+    <xi:include href="xml/gst-validate-reporter.xml"/>
     <xi:include href="xml/gst-validate-monitor-factory.xml"/>
 
   </chapter>

validate/docs/validate/gst-validate-sections.txt

@@ -66,3 +66,27 @@ gst_validate_action_get_type
 gst_validate_action_type_get_type
 gst_validate_scenario_get_type
 </SECTION>
+
+<SECTION>
+<FILE>gst-validate-report</FILE>
+<TITLE>GstValidate reporting system</TITLE>
+GstValidateIssue
+gst_validate_issue_new
+GstValidateReport
+</SECTION>
+
+<SECTION>
+<FILE>gst-validate-reporter</FILE>
+<TITLE>GstValidateReporter</TITLE>
+GstValidateReporter
+GST_VALIDATE_REPORT
+gst_validate_reporter_set_handle_g_logs
+gst_validate_report
+gst_validate_reporter_get_reports_count
+<SUBSECTION Standard>
+GST_TYPE_VALIDATE_REPORTER
+GST_VALIDATE_REPORTER
+GST_IS_VALIDATE_REPORTER
+GST_VALIDATE_REPORTER_GET_INTERFACE
+GST_VALIDATE_REPORTER_CAST
+</SECTION>

validate/gst/validate/gst-validate-reporter.c

@@ -19,6 +19,11 @@
  * Free Software Foundation, Inc., 59 Temple Place - Suite 330,
  * Boston, MA 02111-1307, USA.
  */
+/**
+ * SECTION:gst-validate-reporter
+ * @short_description: A #GInterface that allows #GObject to be used as originator of
+ * issues in the GstValidate reporting system
+ */
 
 #ifdef HAVE_CONFIG_H
 #  include "config.h"
@@ -240,6 +245,18 @@ gst_validate_reporter_g_log_func (const gchar * log_domain,
     GST_VALIDATE_REPORT (reporter, G_LOG_ISSUE, message);
 }
 
+/**
+ * gst_validate_report:
+ * @report: The source of the new report
+ * @issue_id: The #GstValidateIssueId of the issue
+ * @format: The format of the message describing the issue in a printf
+ *       format followed by the parametters.
+ *
+ * Reports a new issue in the GstValidate reporting system with @m
+ * as the source of that issue.
+ *
+ * You can also use #GST_VALIDATE_REPORT instead.
+ */
 void
 gst_validate_report (GstValidateReporter * reporter,
     GstValidateIssueId issue_id, const gchar * format, ...)
@@ -287,6 +304,18 @@ gst_validate_reporter_set_runner (GstValidateReporter * reporter,
   priv->runner = runner;
 }
 
+/**
+ * gst_validate_reporter_set_handle_g_logs:
+ * @reporter: The #GstValidateReporter to set has the handler for g_log
+ *
+ * Set @reporter has the 'source' of any g_log happening during the
+ * execution. Usually the monitor of the first #GstPipeline is used
+ * to handle g_logs.
+ *
+ * Basically this function is used in order to start tracking any
+ * issue reported with g_log in the process into GstValidate report
+ * in the GstValidate reporting system.
+ */
 void
 gst_validate_reporter_set_handle_g_logs (GstValidateReporter * reporter)
 {

validate/gst/validate/gst-validate-reporter.h

@@ -37,6 +37,16 @@ G_BEGIN_DECLS
 #define GST_VALIDATE_REPORTER_GET_INTERFACE(inst) (G_TYPE_INSTANCE_GET_INTERFACE ((inst), GST_TYPE_VALIDATE_REPORTER, GstValidateReporterInterface))
 #define GST_VALIDATE_REPORTER_CAST(obj)           ((GstValidateReporter *) obj)
 
+/**
+ * GST_VALIDATE_REPORT:
+ * @m: The #GstValidateReporter where the issue happened
+ * @issue_id: The #GstValidateIssueId of the issue
+ * @...: The format of the message describing the issue in a printf
+ *       format, followed by the parametters.
+ *
+ * Reports a new issue in the GstValidate reporting system with @m
+ * as the source of that issue.
+ */
 #ifdef G_HAVE_ISO_VARARGS
 #define GST_VALIDATE_REPORT(m, issue_id, ...)				\
   G_STMT_START {							\
@@ -58,7 +68,6 @@ GType gst_validate_reporter_get_type (void);
 
 /**
  * GstValidateInterceptionReturn:
- *
  * @GST_VALIDATE_REPORTER_DROP: The report will be completely ignored.
  * @GST_VALIDATE_REPORTER_KEEP: The report will be kept by the reporter,
  *                              but not reported to the runner.

validate/gst/validate/gst-validate-runner.h

@@ -54,6 +54,7 @@ typedef struct _GstValidateRunnerPrivate GstValidateRunnerPrivate;
 struct _GstValidateRunner {
   GObject 	 object;
 
+  /* <private> */
   GstValidateRunnerPrivate *priv;
 };