docs: improve and update docs

validate/README

@@ -0,0 +1,2 @@
+If you are looking for informations on how to use gst-qa -> docs/qa-usage.txt
+If you are looking for informations on gst-qa design -> docs/qa-design.txt

validate/docs/qa-design.txt

@@ -1,7 +1,37 @@
 
 == Main components
 
-Gst-qa is composed of 3 parts: the monitors, the runner and the reports.
+Gst-qa is composed of 4 parts: the issues, the reports, the runner and the
+reporters.
+
+= Issue
+Gst-QA main target is finding problems in GStreamer elements/pipelines. To
+make it easier to track down exactly what happens, the tests run by Gst-QA use
+an extensible list of 'Issues'. Each Issue describes a potential error
+situation and has an unique ID and a severity level.
+
+The issues list can be extended by 3rd party libraries if specific needs
+should be met.
+
+= Reporters
+A reporter is the object that implements the GstQaReporter interface and is
+responsible for perfoming tests on some target element/scenario. The reporter
+is able to create 'Reports' whenever a test it executes fails.
+
+= Reports
+The GstQaReports are created whenever a test fails, it is posted to the stderr
+and also are posted to the GstQaRunner for accumulation.
+
+Each report contains information about the object that generated the issue,
+the issue associated with the reprot and a specific debug message for the case,
+this helps tracking down the problem and fixing it.
+
+= Runner
+The GstQaRunner is the point of communication for the app to gst-qa
+monitoring. It provides an API to gather reports and to make them acessible
+to the application.
+
+== Reporter types
 
 = Monitors
 The monitors are used to wrap around pipeline (and elements and pads) and
@@ -23,12 +53,9 @@ a new pad is added.
 Most (if not all) the checks are implemented at the GstQaPadMonitor, as it is
 where the data flow happens.
 
-= Runner
-The GstQaRunner is the point of communication for the app to gst-qa
-monitoring. It provides an API to start monitoring a pipeline and then to
-access the results.
+= FileChecker
+The file checker is another reporter that is used to make sure a file has a
+few expected properties. It inspects the file and compares the results with
+expected values set by the user. Values such as file duration, file size, if
+it can be played back and also if its encoding and container types.
 
-= Reports
-The GstQaReports are created when a check fails, it is posted to the runner
-with information about the element that found the problem, along with details
-about it.

validate/docs/qa-usage.txt

@@ -1,13 +1,17 @@
-Using gst-qa is quite simple, there are 2 ways to test your pipeline/element.
+=== Testing with monitors
 
-== Creating a Runner
+Using gst-qa monitors is quite simple, there are 2 ways to test your
+pipeline/element.
+
+== Creating the monitors yourself
 This method requires writing a specific application (or modifying yours) to
-add a GstQaRunner to it. Create a GstQaRunner with gst_qa_runner_new
-(GstPipeline *) and pass the pipeline you want to monitor to it.
+add GstQaMonitors and GstQaRunner to it. Create a GstQaRunner with
+gst_qa_runner_new, then use gst_qa_monitor_factory_create to create monitors
+for your pipeline.
 
-Then call gst_qa_runner_setup to start up the qa system for your pipeline.
-After that just use the GstPipeline as usual and the gst-qa system will
-collect the reports. You can access them after your pipeline has stopped.
+Now all you have to do is use your pipeline as usual, the reports will be
+created and posted to the runner. You can list them after the pipeline
+finishes to look at the issues found.
 
 == Using LD_PRELOAD and an existing application
 If you want to test an already existing application without modifying it. Just
@@ -16,6 +20,15 @@ use:
 LD_PRELOAD=path/to/libgstqa.so yourapp ...
 
 gst-qa will try to replace GstPipeline creating functions and already
-configure runners for you, reports will be printed to stdout when they
-are found.
+configure runners and monitors for you, reports will be printed to stdout when
+they are found.
 
+
+=== Using the file checker
+The GstQaFileChecker is a convenient API to compare a media file properties
+with its expected properties. The uri of the file to be tested and the
+expected values can be configured via gobject properties.
+gst_qa_file_checker_run is used to start the tests.
+
+There is also a convenience tool (gst-qa-file-check) that can be used to
+run the file checker.