TMF: Add documentation for the XML analysis

Change-Id: I305649c313b33ad22b6bfce4e7b6be322d84c704
Signed-off-by: Geneviève Bastien <gbastien+lttng@versatic.net>

7 files changed, 576 insertions, 82 deletions

diff --git a/lttng/org.eclipse.linuxtools.lttng.help/doc/User-Guide.mediawiki b/lttng/org.eclipse.linuxtools.lttng.help/doc/User-Guide.mediawiki
index 429fbccea8..c4f44928ea 100644
--- a/lttng/org.eclipse.linuxtools.lttng.help/doc/User-Guide.mediawiki
+++ b/lttng/org.eclipse.linuxtools.lttng.help/doc/User-Guide.mediawiki
@@ -1833,6 +1833,288 @@ The preference page has several subsections:
 
 This will update all the displayed timestamps.
 
+= Data driven analysis =
+
+It is possible to define custom trace analyses and a way to view them in an XML format. These kind of analyses allow doing more with the trace data than what the default analyses shipped with TMF offer. It can be customized to a specific problem, and fine-tuned to show exactly what you're looking for.
+
+== Importing an XML file containing analysis ==
+
+If you already have an XML file defining state providers and/or views, you can import it in your TMF workspace by right-clicking on the ''Traces'' or ''Experiments'' folder and selecting ''Import XML Analysis''.
+
+[[Image:images/import_XML_analysis.png| Import XML analysis menu]]
+
+You will be prompted to select the file. It will be validated before importing it and if successful, the new analysis and views will be shown under the traces for which they apply. You will need to close any already opened traces and re-open them before the new analysis can be executed.
+
+Right now, there is no way to "unimport" analyses from within the application. A UI to manage the imported analyses is currently being worked on. In the meantime, you can navigate to your workspace directory, and delete the files in .metadata/.plugins/org.eclipse.linuxtools.tmf.analysis.xml.core/xml_files .
+
+== Defining XML components ==
+
+To define XML components, you need to create a new XML file and use the XSD that comes with the XML plugin.
+
+''For now, the XSD is only available through the source code in org.eclipse.linuxtools.tmf.analysis.xml.core/src/org/eclipse/linuxtools/tmf/analysis/xml/core/module/xmlDefinition.xsd''.
+
+An empty file, with no content yet would look like this:
+
+<pre>
+<?xml version="1.0" encoding="UTF-8"?>
+<tmfxml xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+    xsi:noNamespaceSchemaLocation="xmlDefinition.xsd">
+
+</tmfxml>
+</pre>
+
+== Defining an XML state provider ==
+
+The state system is a component of TMF which can track the states of different elements of the system over the duration of a trace. To build this state system, events have to go chronologically through a state provider, which defines what changes are caused by the event to the system.
+
+The state system obtained by the state provider can then be used to populate data-driven views without having to re-read the trace, or to query specific timestamps in the trace without needing to access the trace file.
+
+=== Definitions and example ===
+
+Before we start, we'll define a few terms used in the following sections. The interested reader should read the [[Developer-Guide|Tmf Developer Guide]] for more complete description of the state system and state providers.
+
+* The '''state system''' can be viewed as a model of the system, where the different elements (attributes) can be seen as a tree, and their evolution (states) is tracked through time.
+
+* '''Attribute''': An attribute is the smallest element of the model that can be in any particular state. Since many attributes may have the same name, each attribute is represented by its full path in the attribute tree.
+
+* '''State''': A state is a value assigned to an attribute at a given time. Each model has its own state values.
+
+* '''Attribute tree''': Elements in the model can be placed in a tree-like structure, for logical grouping. Each element in the tree can have both children and a state. Also, the tree is just a logical structure, all elements may be top-level elements.
+
+* '''State history''': Whereas the attribute tree may be seen as the first dimension of the state system, the state history is the second dimension, over time. It tracks the intervals at which an attribute was in a given state.
+
+In the following sections, we'll use an example trace with the following events:
+
+* start(number): A new task with ID 'number' just started.
+* execute(number, fct_name): The task with ID 'number' is executing a critical section named 'fct_name'.
+* wait(number): The task with ID 'number' cannot execute a critical section and needs to wait for it.
+* exec_end(fct_name): A task finished executing the critical section named 'fct_name'.
+* stop(number): The task with ID 'number' has just finished.
+
+=== Determining the state system structure ===
+
+The first thing to do is to determine the attribute tree we'll use to represent the model of the system. The attribute tree is like a file system with directories and files, where files are logically gathered in the same parent directory. There is no one good way to build a tree, the logic will depend on the situation and on the person defining it.
+
+The generated state system may be used later on to populate views, so attributes of the tree could be grouped in such a way as to make it easy to reach them with a simple path. The view will then be more simple.
+
+In our example case, we'll want to track the status of each task and, for each critical section, which task is running them.
+
+<pre>
+|- Tasks
+|    |- 1
+|    |- 2
+|   ...
+|- Critical section
+     |- Crit_sect1
+     |- Crit_sect2
+    ...
+</pre>
+
+Then we determine how each event will affect the state of the attributes. But first, let's ask ourselves what values should each state take.
+
+Let's see with the tree:
+
+<pre>
+|- Tasks            -> Empty
+|    |- 1           -> Each task can be in one of
+|    |- 2             RUNNING, CRITICAL, WAITING
+|   ...
+|- Critical section -> Empty
+     |- Crit_sect1  -> Each critical section will hold the currently running task number
+     |- Crit_sect2
+    ...
+</pre>
+
+Then we determine how each event will affect the state of the attributes. In the attribute paths below, elements in {} are values coming from the trace event, while strings are constants. For the sake of simplicity, we'll say "update attribute", but if an attribute does not exist, it will be created.
+
+* start(number): Update state value of attribute "Tasks/{number}" to "RUNNING".
+* execute(number, fct_name): Update state value of attribute "Tasks/{number}" to "CRITICAL" and Update attribute "Critical section/{fct_name}" to "{number}".
+* wait(number): Update state value of attribute "Tasks/{number}" to "WAITING".
+* exec_end(fct_name): Update state value of attribute "Tasks/{valueOf Critical section/{fct_name}}" to RUNNING and update "Critical section/{fct_name}" to null.
+* stop(number): Update state value of attribute "Tasks/{number}" to null.
+
+=== Writing the XML state provider ===
+
+Once the model is done at a high level, it is time to translate it to an XML data-driven analysis. For details on how to use each XML element, refer to the documentation available in the XSD files. Some elements will be commented on below.
+
+First define the state provider element.
+
+The "version" attribute indicates which version of the state system is defined here. Once a state provider has been defined for a trace type, it will typically be used by a team of people and it may be modified over time. This version number should be bumped each time a new version of the state provider is published. This will force a rebuild of any existing state histories (if applicable) whose version number is different from the current one.
+
+The "id" attribute uniquely identifies this state provider, and the analysis that will contain it.
+
+<pre>
+<stateProvider version="0" id="my.test.state.provider">
+</pre>
+
+Optional header information can be added to the state provider. A "traceType" should be defined to tell TMF which trace type this analysis will apply to. If no tracetype is specified, the analysis will appear under every trace. A "label" can optionally be added to have a more user-friendly name for the analysis.
+
+<pre>
+<head>
+    <traceType id="my.trace.id" />
+    <label value="My test analysis" />
+</head>
+</pre>
+
+If pre-defined values will be used in the state provider, they must be defined before the state providers. They can then be referred to in the state changes by name, preceded by the '$' sign. It is not necessary to use pre-defined values, the state change can use values like (100, 101, 102) directly.
+
+<pre>
+<definedValue name="RUNNING" value="100" />
+<definedValue name="CRITICAL" value="101" />
+<definedValue name="WAITING" value="102" />
+</pre>
+
+The following event handler shows what to do with the event named ''start''. It causes one state change. The sequence of '''stateAttribute''' elements represents the path to the attribute in the attribute tree, each element being one level of the tree. The '''stateValue''' indicates which value to assign to the attribute at the given path. The "$RUNNING" value means it will use the predefined value named RUNNING above.
+
+Suppose the actual event is ''start(3)''. The result of this state change is that at the time of the event, the state system attribute "Tasks/3" will have value 100.
+
+<pre>
+<eventHandler eventName="start">
+    <stateChange>
+        <stateAttribute type="constant" value="Tasks" />
+        <stateAttribute type="eventField" value="number" />
+        <stateValue type="int" value="$RUNNING" />
+    </stateChange>
+</eventHandler>
+</pre>
+
+The full XML file for the example above would look like this:
+
+<pre>
+<?xml version="1.0" encoding="UTF-8"?>
+<tmfxml xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../../org.eclipse.linuxtools.tmf.analysis.xml.core/src/org/eclipse/linuxtools/tmf/analysis/xml/core/module/xmlDefinition.xsd">
+    <stateProvider version="0" id="my.test.state.provider">
+        <head>
+            <traceType id="my.trace.id" />
+            <label value="My test analysis" />
+        </head>
+
+        <definedValue name="RUNNING" value="100" />
+        <definedValue name="CRITICAL" value="101" />
+        <definedValue name="WAITING" value="102" />
+
+        <eventHandler eventName="start">
+            <stateChange>
+                <stateAttribute type="constant" value="Tasks" />
+                <stateAttribute type="eventField" value="number" />
+                <stateValue type="int" value="$RUNNING" />
+            </stateChange>
+        </eventHandler>
+        <eventHandler eventName="execute">
+            <stateChange>
+                <stateAttribute type="constant" value="Tasks" />
+                <stateAttribute type="eventField" value="number" />
+                <stateValue type="int" value="$CRITICAL" />
+            </stateChange>
+            <stateChange>
+                <stateAttribute type="constant" value="Critical section" />
+                <stateAttribute type="eventField" value="fct_name" />
+                <stateValue type="eventField" value="number" />
+            </stateChange>
+        </eventHandler>
+        <eventHandler eventName="wait">
+            <stateChange>
+                <stateAttribute type="constant" value="Tasks" />
+                <stateAttribute type="eventField" value="number" />
+                <stateValue type="int" value="$WAITING" />
+            </stateChange>
+        </eventHandler>
+        <eventHandler eventName="exec_end">
+            <stateChange>
+                <stateAttribute type="constant" value="Tasks" />
+                <stateAttribute type="query">
+                    <stateAttribute type="constant" value="Critical section" />
+                    <stateAttribute type="eventField" value="fct_name" />
+                </stateAttribute>
+                <stateValue type="int" value="$RUNNING" />
+            </stateChange>
+            <stateChange>
+                <stateAttribute type="constant" value="Critical section" />
+                <stateAttribute type="eventField" value="fct_name" />
+                <stateValue type="null" />
+            </stateChange>
+        </eventHandler>
+        <eventHandler eventName="stop">
+            <stateChange>
+                <stateAttribute type="constant" value="Tasks" />
+                <stateAttribute type="eventField" value="number" />
+                <stateValue type="null" />
+            </stateChange>
+        </eventHandler>
+    </stateProvider>
+</tmfxml>
+</pre>
+
+=== Debugging the XML state provider ===
+
+To debug the state system that was generated by the XML state provider, one could use the [[#State System Explorer View]], along with the events editor. By selecting an event, you can see what changes this event caused and the states of other attributes at the time.
+
+If there are corrections to make, you may modify the XML state provider file, and re-import it. To re-run the analysis, you must first delete the supplementary files by right-clicking on your trace, and selecting ''Delete supplementary files...''. Check you analysis's .ht file, so that the analysis will be run again when the trace is reopened. The supplementary file deletion will have closed the trace, so it needs to be opened again to use the newly imported analysis file.
+
+If modifications are made to the XML state provider after it has been "published", the '''version''' attribute of the '''xmlStateProvider''' element should be updated. This avoids having to delete each trace's supplementary file manually. If the saved state system used a previous version, it will automatically be rebuilt from the XML file.
+
+== Defining an XML time graph view ==
+
+A time graph view is a view divided in two, with a tree viewer on the left showing information on the different entries to display and a Gantt-like viewer on the right, showing the state of the entries over time. The [[#Control_Flow_View | Control Flow View]] is an example of a time graph view.
+
+Such views can be defined in XML using the data in the state system. The state system itself could have been built by an XML-defined state provider or by any pre-defined Java analysis. It only requires knowing the structure of the state system, which can be explored using the [[#State System Explorer View]] (or programmatically using the methods in ''ITmfStateSystem'').
+
+In the example above, suppose we want to display the status for each task. In the state system, it means the path of the entries to display is "Tasks/*". The attribute whose value should be shown in the Gantt chart is the entry attribute itself. So the XML to display these entries would be as such:
+
+<pre>
+<entry path="Tasks/*">
+    <display type="self" />
+</entry>
+</pre>
+
+But first, the view has to be declared. It has an ID, to uniquely identify this view among all the available XML files.
+
+<pre>
+<timeGraphView id="my.test.time.graph.view">
+</pre>
+
+Optional header information can be added to the view. '''analysis''' elements will associate the view only to the analysis identified by the "id" attribute. It can be either the ID of the state provider, like in this case, or the analysis ID of any analysis defined in Java. If no analysis is specified, the view will appear under every analysis with a state system. The '''label''' element allows to give a more user-friendly name to the view. The label does not have to be unique. As long as the ID is unique, views for different analyses can use the same name.
+
+<pre>
+<head>
+    <analysis id="my.test.state.provider" />
+    <label value="My Sample XML View" />
+</head>
+</pre>
+
+Also, if the values of the attributes to display are known, they can be defined, along with a text to explain them and a color to draw them with. Note that the values are the same as defined in the state provider, but the name does not have to be the same. While in the state provider, a simple constant string makes sense to use in state changes. But in the view, the name will appear in the legend, so a user-friendly text is more appropriate.
+
+<pre>
+<definedValue name="The process is running" value="100" color="#118811" />
+<definedValue name="Critical section" value="101" color="#881111" />
+<definedValue name="Waiting for critical section" value="102" color="#AEB522" />
+</pre>
+
+Here is the full XML for the time graph view:
+
+<pre>
+<tmfxml xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../../org.eclipse.linuxtools.tmf.analysis.xml.core/src/org/eclipse/linuxtools/tmf/analysis/xml/core/module/xmlDefinition.xsd">
+    <timeGraphView id="my.test.time.graph.view">
+        <head>
+            <analysis id="my.test.state.provider" />
+            <label value="My Sample XML View" />
+        </head>
+
+        <definedValue name="The process is running" value="100" color="#118811" />
+        <definedValue name="Critical section" value="101" color="#881111" />
+        <definedValue name="Waiting for critical section" value="102" color="#AEB522" />
+
+        <entry path="Tasks/*">
+            <display type="self" />
+        </entry>
+    </timeGraphView>
+</tmfxml>
+</pre>
+
+The following screenshot shows the result of the preceding example on a test trace. The trace used, as well as the XML file are available [http://secretaire.dorsal.polymtl.ca/~gbastien/Xml4Traces/XML_documentation_example.tar.gz here].
+
+[[Image:images/Xml_analysis_screenshot.png| XML analysis with view]]
+
 = Limitations =
 
 * When parsing text traces, the timestamps are assumed to be in the local time zone. This means that when combining it to CTF binary traces, there could be offsets by a few hours depending on where the traces were taken and where they were read.
diff --git a/lttng/org.eclipse.linuxtools.lttng.help/doc/images/Xml_analysis_screenshot.png b/lttng/org.eclipse.linuxtools.lttng.help/doc/images/Xml_analysis_screenshot.png
new file mode 100644
index 0000000000..292c239ba3
--- /dev/null
+++ b/lttng/org.eclipse.linuxtools.lttng.help/doc/images/Xml_analysis_screenshot.png
diff --git a/lttng/org.eclipse.linuxtools.lttng.help/doc/images/import_XML_analysis.png b/lttng/org.eclipse.linuxtools.lttng.help/doc/images/import_XML_analysis.png
new file mode 100644
index 0000000000..70836df2e5
--- /dev/null
+++ b/lttng/org.eclipse.linuxtools.lttng.help/doc/images/import_XML_analysis.png
diff --git a/lttng/org.eclipse.linuxtools.tmf.analysis.xml.core/src/org/eclipse/linuxtools/tmf/analysis/xml/core/module/xmlCommon.xsd b/lttng/org.eclipse.linuxtools.tmf.analysis.xml.core/src/org/eclipse/linuxtools/tmf/analysis/xml/core/module/xmlCommon.xsd
index 163a86bef3..453a219155 100644
--- a/lttng/org.eclipse.linuxtools.tmf.analysis.xml.core/src/org/eclipse/linuxtools/tmf/analysis/xml/core/module/xmlCommon.xsd
+++ b/lttng/org.eclipse.linuxtools.tmf.analysis.xml.core/src/org/eclipse/linuxtools/tmf/analysis/xml/core/module/xmlCommon.xsd
@@ -14,17 +14,31 @@
 	attributeFormDefault="unqualified" elementFormDefault="qualified">
 
 	<xs:complexType name="definedValue">
-		<xs:attribute name="name" type="xs:string" use="required" />
-		<xs:attribute name="value" type="xs:string" use="required" />
-		<xs:attribute name="color" type="xs:string" use="optional" />
+		<xs:annotation>
+			<xs:documentation>Maps a string (usually a human-readable value used by the XML elements) to another string (a value in the system, which can be converted to an integer, long by the a stateValue element or used as-is).</xs:documentation></xs:annotation>
+		<xs:attribute name="name" type="xs:string" use="required" >
+			<xs:annotation>
+				<xs:documentation>The human-readable string to identify this value. This is what will be manipulated by the XML and shown to the end-user (if applicable).</xs:documentation></xs:annotation></xs:attribute>
+		<xs:attribute name="value" type="xs:string" use="required" >
+			<xs:annotation>
+				<xs:documentation>A system value the 'name' maps to. It will usually not be shown to the end user.</xs:documentation></xs:annotation></xs:attribute>
+		<xs:attribute name="color" type="xs:string" use="optional" >
+			<xs:annotation>
+				<xs:documentation>Optional color attribute to this mapping. This attribute is used in XML-defined views to represent this mapping.</xs:documentation></xs:annotation></xs:attribute>
 	</xs:complexType>
 
 	<xs:complexType name="location">
+		<xs:annotation>
+			<xs:documentation>Define a path in a state system, that can then be used as a shortcut in other XML elements.</xs:documentation></xs:annotation>
 		<xs:sequence>
-			<xs:element maxOccurs="unbounded" minOccurs="0" name="stateAttribute" type="stateAttribute" />
+			<xs:element maxOccurs="unbounded" minOccurs="0" name="stateAttribute" type="stateAttribute" >
+				<xs:annotation>
+					<xs:documentation>Define each element of the path represented by this location. For instance, if location "abc" has path "a/b/c", there would be a sequence of 3 stateAttribute elements of type constant.</xs:documentation></xs:annotation></xs:element>
 		</xs:sequence>
-		<xs:attribute name="id" type="xs:string" use="required" />
+		<xs:attribute name="id" type="xs:string" use="required" >
+			<xs:annotation>
+				<xs:documentation>The identifier of this location, used inside the XML element in the scope of which it is defined.</xs:documentation></xs:annotation></xs:attribute>
 		<xs:anyAttribute />
 	</xs:complexType>
 
-</xs:schema>
\ No newline at end of file
+</xs:schema>
diff --git a/lttng/org.eclipse.linuxtools.tmf.analysis.xml.core/src/org/eclipse/linuxtools/tmf/analysis/xml/core/module/xmlDefinition.xsd b/lttng/org.eclipse.linuxtools.tmf.analysis.xml.core/src/org/eclipse/linuxtools/tmf/analysis/xml/core/module/xmlDefinition.xsd
index 5c81260b22..7f8a8f363a 100644
--- a/lttng/org.eclipse.linuxtools.tmf.analysis.xml.core/src/org/eclipse/linuxtools/tmf/analysis/xml/core/module/xmlDefinition.xsd
+++ b/lttng/org.eclipse.linuxtools.tmf.analysis.xml.core/src/org/eclipse/linuxtools/tmf/analysis/xml/core/module/xmlDefinition.xsd
@@ -19,8 +19,12 @@
 	<xs:element name="tmfxml">
 		<xs:complexType>
 			<xs:choice maxOccurs="unbounded">
-				<xs:element maxOccurs="unbounded" minOccurs="0" name="timeGraphView" type="timeGraphView" />
-				<xs:element maxOccurs="unbounded" minOccurs="0" name="stateProvider" type="stateProvider" />
+				<xs:element maxOccurs="unbounded" minOccurs="0" name="timeGraphView" type="timeGraphView" >
+					<xs:annotation>
+						<xs:documentation>Define a new time graph view.</xs:documentation></xs:annotation></xs:element>
+				<xs:element maxOccurs="unbounded" minOccurs="0" name="stateProvider" type="stateProvider" >
+					<xs:annotation>
+						<xs:documentation>Define a new state provider</xs:documentation></xs:annotation></xs:element>
 			</xs:choice>
 		</xs:complexType>
 	</xs:element>
diff --git a/lttng/org.eclipse.linuxtools.tmf.analysis.xml.core/src/org/eclipse/linuxtools/tmf/analysis/xml/core/module/xmlStateProvider.xsd b/lttng/org.eclipse.linuxtools.tmf.analysis.xml.core/src/org/eclipse/linuxtools/tmf/analysis/xml/core/module/xmlStateProvider.xsd
index 8cb7a9b923..dcafbfd6b6 100644
--- a/lttng/org.eclipse.linuxtools.tmf.analysis.xml.core/src/org/eclipse/linuxtools/tmf/analysis/xml/core/module/xmlStateProvider.xsd
+++ b/lttng/org.eclipse.linuxtools.tmf.analysis.xml.core/src/org/eclipse/linuxtools/tmf/analysis/xml/core/module/xmlStateProvider.xsd
@@ -14,144 +14,282 @@
 	attributeFormDefault="unqualified" elementFormDefault="qualified">
 
 	<xs:complexType name="stateProvider">
+		<xs:annotation>
+			<xs:documentation>Declares a data-driven state provider which defines how events change the state of attributes of the system. Each state provider defined in XML will become an analysis in TMF.</xs:documentation></xs:annotation>
 		<xs:sequence maxOccurs="1" minOccurs="1">
-			<xs:element maxOccurs="1" minOccurs="0" name="head" type="headProvider" />
-			<xs:element maxOccurs="unbounded" minOccurs="0" name="definedValue" type="definedValue" />
-			<xs:element maxOccurs="unbounded" minOccurs="0" name="location" type="location" />
-			<xs:element maxOccurs="unbounded" minOccurs="1" name="eventHandler" type="eventHandler" />
+			<xs:element maxOccurs="1" minOccurs="0" name="head" type="headProvider" >
+				<xs:annotation>
+					<xs:documentation>Provide meta-information on this state provider, like labels and applicable trace types.</xs:documentation></xs:annotation></xs:element>
+			<xs:element maxOccurs="unbounded" minOccurs="0" name="definedValue" type="definedValue" >
+				<xs:annotation>
+					<xs:documentation>Define a value that maps a string used in the state provider to a numbered value.</xs:documentation></xs:annotation></xs:element>
+			<xs:element maxOccurs="unbounded" minOccurs="0" name="location" type="location" >
+				<xs:annotation>
+					<xs:documentation>Declare shortcuts to frequently used attribute/data locations. For instance, if a path to an often-used attribute is CPUs/{event.some_field}/Threads/Status, it may be a good idea to put this path in a location and then use the location name in the event handlers.</xs:documentation></xs:annotation></xs:element>
+			<xs:element maxOccurs="unbounded" minOccurs="1" name="eventHandler" type="eventHandler" >
+				<xs:annotation>
+					<xs:documentation>Define how a given event will modify the state system being built. For each event in the trace that causes a state change, a event handler should be defined.</xs:documentation></xs:annotation></xs:element>
 		</xs:sequence>
-		<xs:attribute name="id" type="xs:string" use="required" />
-		<xs:attribute name="version" type="xs:integer" use="required" />
+		<xs:attribute name="id" type="xs:string" use="required" >
+			<xs:annotation>
+				<xs:documentation>The unique ID of this state provider. It will be used to identify the analysis that will be built from this state provider.</xs:documentation></xs:annotation></xs:attribute>
+		<xs:attribute name="version" type="xs:integer" use="required" >
+			<xs:annotation>
+				<xs:documentation>The version ID of this state provider. Whenever the state provider changes so that the resulting state system is different from previous versions, this version number should be bumped.</xs:documentation></xs:annotation></xs:attribute>
 	</xs:complexType>
 
 	<xs:complexType name="headProvider">
+		<xs:annotation>
+			<xs:documentation>Declares the meta-information that can be defined for an XML state provider.</xs:documentation></xs:annotation>
 		<xs:sequence>
 			<xs:element maxOccurs="unbounded" minOccurs="0" name="traceType">
+				<xs:annotation>
+					<xs:documentation>Indicate that the state provider applies to a given trace type.</xs:documentation></xs:annotation>
 				<xs:complexType>
-					<xs:attribute name="id" use="required" />
+					<xs:attribute name="id" use="required" >
+						<xs:annotation>
+							<xs:documentation>The ID of the trace type, as declared in a org.eclipse.linuxtools.tmf.core.tracetype extension point or a custom trace parser. For example: "org.eclipse.linuxtools.lttng2.kernel.tracetype" or "org.eclipse.linuxtools.lttng2.ust.tracetype" for respectively LTTng Kernel and LTTng UST traces.</xs:documentation></xs:annotation></xs:attribute>
 				</xs:complexType>
 			</xs:element>
 			<xs:element maxOccurs="1" minOccurs="0" name="label">
+				<xs:annotation>
+					<xs:documentation>Add a label to the state provider. If provided, this text will be the name of the analysis that the user will see in TMF.</xs:documentation></xs:annotation>
 				<xs:complexType>
-					<xs:attribute name="value" />
+					<xs:attribute name="value" >
+						<xs:annotation>
+							<xs:documentation>The text to name this state provider (and the analysis it will generate).</xs:documentation></xs:annotation></xs:attribute>
 				</xs:complexType>
 			</xs:element>
 		</xs:sequence>
 	</xs:complexType>
 
 	<xs:complexType name="eventHandler">
+		<xs:annotation>
+			<xs:documentation>Define how an event modifies the state of the system. There should be one event handler for each event causing a state change.</xs:documentation></xs:annotation>
 		<xs:sequence>
-			<xs:element maxOccurs="unbounded" minOccurs="1" name="stateChange" type="stateChange" />
+			<xs:element maxOccurs="unbounded" minOccurs="1" name="stateChange" type="stateChange" >
+				<xs:annotation>
+					<xs:documentation>Define how the state system is modified by the event. An event may cause more than one state change.</xs:documentation></xs:annotation></xs:element>
 		</xs:sequence>
-		<xs:attribute name="eventName" type="xs:string" use="required" />
+		<xs:attribute name="eventName" type="xs:string" use="required" >
+			<xs:annotation>
+				<xs:documentation>Name of the event that causes a state change.</xs:documentation></xs:annotation></xs:attribute>
 		<xs:anyAttribute />
 	</xs:complexType>
 
 	<xs:complexType name="stateChange">
+		<xs:annotation>
+			<xs:documentation>Define a change of state in the state system being built.</xs:documentation></xs:annotation>
 		<xs:choice maxOccurs="1" minOccurs="1">
 			<xs:sequence maxOccurs="1" minOccurs="1">
-				<xs:element maxOccurs="unbounded" minOccurs="1" name="stateAttribute" type="stateAttribute" />
-				<xs:element maxOccurs="1" minOccurs="1" name="stateValue" type="stateValue" />
+				<xs:annotation>
+					<xs:documentation>Describe a single attribute assignation. Simply put: a state change where path/to/attribute=value.</xs:documentation></xs:annotation>
+				<xs:element maxOccurs="unbounded" minOccurs="1" name="stateAttribute" type="stateAttribute" >
+					<xs:annotation>
+						<xs:documentation>Explain how to reach an attribute in the state system. It describes the path/to/attribute.</xs:documentation></xs:annotation></xs:element>
+				<xs:element maxOccurs="1" minOccurs="1" name="stateValue" type="stateValue" >
+					<xs:annotation>
+						<xs:documentation>Explain how to obtain the value of the state attribute to modify.</xs:documentation></xs:annotation></xs:element>
 			</xs:sequence>
 			<xs:sequence maxOccurs="1" minOccurs="1">
-				<xs:element maxOccurs="1" minOccurs="1" name="if" type="conditionSingle" />
-				<xs:element maxOccurs="1" minOccurs="1" name="then" type="stateChange" />
-				<xs:element maxOccurs="1" minOccurs="0" name="else" type="stateChange" />
+				<xs:annotation>
+					<xs:documentation>Describe a conditional state change, where different path conditions may lead to different state changes.</xs:documentation></xs:annotation>
+				<xs:element maxOccurs="1" minOccurs="1" name="if" type="conditionSingle" >
+					<xs:annotation>
+						<xs:documentation>Define the condition to verify.</xs:documentation></xs:annotation></xs:element>
+				<xs:element maxOccurs="1" minOccurs="1" name="then" type="stateChange" >
+					<xs:annotation>
+						<xs:documentation>Define the state change to use if the previous condition is true.</xs:documentation></xs:annotation></xs:element>
+				<xs:element maxOccurs="1" minOccurs="0" name="else" type="stateChange" >
+					<xs:annotation>
+						<xs:documentation>Optionally define the state change to use if the condition is false.</xs:documentation></xs:annotation></xs:element>
 			</xs:sequence>
 		</xs:choice>
 	</xs:complexType>
 
 	<xs:complexType name="condition">
+		<xs:annotation>
+			<xs:documentation>Define a conditional statement. Conditions may use values of the state system or from the event being handled. This element defines a statement in the form of "if (some_path == value)".</xs:documentation></xs:annotation>
 		<xs:sequence maxOccurs="1" minOccurs="1">
 			<xs:choice maxOccurs="1" minOccurs="1">
-				<xs:element maxOccurs="unbounded" minOccurs="1" name="stateAttribute" type="stateAttribute" />
-				<xs:element maxOccurs="1" minOccurs="1" name="field" type="eventField" />
+				<xs:element maxOccurs="unbounded" minOccurs="1" name="stateAttribute" type="stateAttribute" >
+					<xs:annotation>
+						<xs:documentation>Compare the current value of an attribute of the state system.</xs:documentation></xs:annotation></xs:element>
+				<xs:element maxOccurs="1" minOccurs="1" name="field" type="eventField" >
+					<xs:annotation>
+						<xs:documentation>Compare the value of an event field.</xs:documentation></xs:annotation></xs:element>
 			</xs:choice>
-			<xs:element maxOccurs="1" minOccurs="1" name="stateValue" type="stateValue" />
+			<xs:element maxOccurs="1" minOccurs="1" name="stateValue" type="stateValue" >
+				<xs:annotation>
+					<xs:documentation>Define the value to compare to.</xs:documentation></xs:annotation></xs:element>
 		</xs:sequence>
 		<xs:anyAttribute />
 	</xs:complexType>
 
 	<xs:complexType name="conditionSingle">
+		<xs:annotation>
+			<xs:documentation>Define a conditional statement with only one child. From this element, a condition may be composed of other conditional elements to create more complex conditional statements.</xs:documentation></xs:annotation>
 		<xs:choice maxOccurs="1" minOccurs="1">
-			<xs:element name="condition" type="condition" />
-			<xs:element name="not" type="conditionSingle" />
-			<xs:element name="and" type="conditionMultiple" />
-			<xs:element name="or" type="conditionMultiple" />
+			<xs:element name="condition" type="condition" >
+				<xs:annotation>
+					<xs:documentation>Define a condition element, in the form "if (some_path == value)".</xs:documentation></xs:annotation></xs:element>
+			<xs:element name="not" type="conditionSingle" >
+				<xs:annotation>
+					<xs:documentation>Negate the result of the following condition, allowing statements of the form "if (!cond)".</xs:documentation></xs:annotation></xs:element>
+			<xs:element name="and" type="conditionMultiple" >
+				<xs:annotation>
+					<xs:documentation>ANDs 2 conditional statements, allowing statements of the form "if (condA AND condB)"</xs:documentation></xs:annotation></xs:element>
+			<xs:element name="or" type="conditionMultiple" >
+				<xs:annotation>
+					<xs:documentation>ORs 2 conditional statements, allowing statements of the form "if (condA OR condB)"</xs:documentation></xs:annotation></xs:element>
 		</xs:choice>
 		<xs:anyAttribute />
 	</xs:complexType>
 
 	<xs:complexType name="conditionMultiple">
+		<xs:annotation>
+			<xs:documentation>Allows the composition of more than one conditional statements.</xs:documentation></xs:annotation>
 		<xs:sequence maxOccurs="unbounded" minOccurs="1">
-			<xs:element maxOccurs="1" minOccurs="0" name="condition" type="condition" />
-			<xs:element maxOccurs="1" minOccurs="0" name="or" type="conditionMultiple" />
-			<xs:element maxOccurs="1" minOccurs="0" name="and" type="conditionMultiple" />
-			<xs:element maxOccurs="1" minOccurs="0" name="not" type="conditionSingle" />
+			<xs:element maxOccurs="1" minOccurs="0" name="condition" type="condition" >
+				<xs:annotation>
+					<xs:documentation>Define a condition element, in the form "if (some_path == value)".</xs:documentation></xs:annotation></xs:element>
+			<xs:element maxOccurs="1" minOccurs="0" name="or" type="conditionMultiple" >
+				<xs:annotation>
+					<xs:documentation>ORs 2 conditional statements, allowing statements of the form "if (condA OR condB)"</xs:documentation></xs:annotation></xs:element>
+			<xs:element maxOccurs="1" minOccurs="0" name="and" type="conditionMultiple" >
+				<xs:annotation>
+					<xs:documentation>ANDs 2 conditional statements, allowing statements of the form "if (condA AND condB)"</xs:documentation></xs:annotation></xs:element>
+			<xs:element maxOccurs="1" minOccurs="0" name="not" type="conditionSingle" >
+				<xs:annotation>
+					<xs:documentation>Negate the result of the following condition, allowing statements of the form "if (!cond)".</xs:documentation></xs:annotation></xs:element>
 		</xs:sequence>
 		<xs:anyAttribute />
 	</xs:complexType>
 
 	<xs:complexType name="stateAttribute">
+		<xs:annotation>
+			<xs:documentation>Define a path to an attribute of the state system.</xs:documentation></xs:annotation>
 		<xs:sequence>
-			<xs:element maxOccurs="unbounded" minOccurs="0" name="stateAttribute" type="stateAttribute" />
+			<xs:element maxOccurs="unbounded" minOccurs="0" name="stateAttribute" type="stateAttribute" >
+				<xs:annotation>
+					<xs:documentation>If the type is a "query", those stateAttribute elements describe the elements of the query.</xs:documentation></xs:annotation></xs:element>
 		</xs:sequence>
 		<xs:attribute name="type" use="required">
+			<xs:annotation>
+				<xs:documentation>The type of path to this attribute. The meaning of those paths type will depend on the context where the stateAttribute is being used. Not all types will make sense everywhere.</xs:documentation></xs:annotation>
 			<xs:simpleType>
 				<xs:restriction base="xs:string">
-					<xs:enumeration value="null" />
-					<xs:enumeration value="constant" />
-					<xs:enumeration value="eventField" />
-					<xs:enumeration value="location" />
-					<xs:enumeration value="query" />
+					<xs:enumeration value="null" >
+						<xs:annotation>
+							<xs:documentation>This type does not change the current attribute. Whatever attribute was the reference attribute at a given time, it will be returned as is.</xs:documentation></xs:annotation></xs:enumeration>
+					<xs:enumeration value="constant" >
+						<xs:annotation>
+							<xs:documentation>This type identifies the state system attribute by a constant string. For instance, if the first level attribute of the state system is "Threads", then a constant type with "Threads" value should be used.</xs:documentation></xs:annotation></xs:enumeration>
+					<xs:enumeration value="eventField" >
+						<xs:annotation>
+							<xs:documentation>This type identifies the attribute by the value of an event field. Note that the event field corresponds to the attribute name, not its value. For example, if the event has a field called "current_cpu" with a value of "2", "2" would be the attribute name we want.</xs:documentation></xs:annotation></xs:enumeration>
+					<xs:enumeration value="location" >
+						<xs:annotation>
+							<xs:documentation>This type indicates that the path to the attribute is at the specified location. Location simply avoids having to write full path to an attribute each time it is being used, but the location itself is a sequence of stateAttribute elements. For example, if we previously defined a location named "CurrentThead" for path "CPUs/{current_cpu}/CurrentThread", we can use a stateAttribute of type location with "CurrentThread" value.</xs:documentation></xs:annotation></xs:enumeration>
+					<xs:enumeration value="query" >
+						<xs:annotation>
+							<xs:documentation>This type indicates that the path to the attribute is the result of a query. If this type is selected, a sequence of stateAttribute elements needs to be specified for this state attribute. The result of the query is the attribute name of the current element. For example, if the attribute we want is the PID of the current process on CPU 0, that PID can be found through the query "CPUs/0/CurrentThread". The value of this attribute would be, for example, 1234, the attribute we are looking for.</xs:documentation></xs:annotation></xs:enumeration>
 				</xs:restriction>
 			</xs:simpleType>
 		</xs:attribute>
-		<xs:attribute name="value" type="xs:string" />
+		<xs:attribute name="value" type="xs:string" >
+			<xs:annotation>
+				<xs:documentation>The value of this state attribute. A value should be specified only if the type is "constant", "eventField" or "location".</xs:documentation></xs:annotation></xs:attribute>
 	</xs:complexType>
 
 	<xs:complexType name="stateValue">
+		<xs:annotation>
+			<xs:documentation>Define a value, that can be assigned to an attribute of the state system.</xs:documentation></xs:annotation>
 		<xs:sequence>
-			<xs:element maxOccurs="unbounded" minOccurs="0" name="stateAttribute" type="stateAttribute" />
+			<xs:annotation>
+				<xs:documentation>For a "query" value type, a sequence of stateAttributes will define the query whose result is the value.</xs:documentation></xs:annotation>
+			<xs:element maxOccurs="unbounded" minOccurs="0" name="stateAttribute" type="stateAttribute" ></xs:element>
 		</xs:sequence>
 		<xs:attribute name="type" use="required">
+			<xs:annotation>
+				<xs:documentation>The type of this state value. It will describe how to obtain to value and/or what to do with it.</xs:documentation></xs:annotation>
 			<xs:simpleType>
 				<xs:restriction base="xs:string">
-					<xs:enumeration value="null" />
-					<xs:enumeration value="int" />
-					<xs:enumeration value="long" />
-					<xs:enumeration value="string" />
-					<xs:enumeration value="eventField" />
-					<xs:enumeration value="eventName" />
-					<xs:enumeration value="delete" />
-					<xs:enumeration value="query" />
+					<xs:enumeration value="null" >
+						<xs:annotation>
+							<xs:documentation>Indicate that the value is a null value.</xs:documentation></xs:annotation></xs:enumeration>
+					<xs:enumeration value="int" >
+						<xs:annotation>
+							<xs:documentation>The value is a constant of type integer.</xs:documentation></xs:annotation></xs:enumeration>
+					<xs:enumeration value="long" >
+						<xs:annotation>
+							<xs:documentation>The value is a constant of type long</xs:documentation></xs:annotation></xs:enumeration>
+					<xs:enumeration value="string" >
+						<xs:annotation>
+							<xs:documentation>The value is a constant of type string</xs:documentation></xs:annotation></xs:enumeration>
+					<xs:enumeration value="eventField" >
+						<xs:annotation>
+							<xs:documentation>The value is the content of an event field. The "value" attribute is the field name. To convert this field to a certain type, attribute "forcedType" may be used.</xs:documentation></xs:annotation></xs:enumeration>
+					<xs:enumeration value="eventName" >
+						<xs:annotation>
+							<xs:documentation>The value is the name of the event.</xs:documentation></xs:annotation></xs:enumeration>
+					<xs:enumeration value="delete" >
+						<xs:annotation>
+							<xs:documentation>Indicate that the attribute the value is to be applied to should be deleted.</xs:documentation></xs:annotation></xs:enumeration>
+					<xs:enumeration value="query" >
+						<xs:annotation>
+							<xs:documentation>The value is the result of a query to the state system. If this type is selected, a sequence of stateAttributes must be defined in this stateValue element.</xs:documentation></xs:annotation></xs:enumeration>
 				</xs:restriction>
 			</xs:simpleType>
 		</xs:attribute>
-		<xs:attribute name="increment" type="xs:boolean" />
+		<xs:attribute name="increment" type="xs:boolean" >
+			<xs:annotation>
+				<xs:documentation>Indicate that the current value will be added to any previously available value.</xs:documentation></xs:annotation></xs:attribute>
 		<xs:attribute name="stack">
+			<xs:annotation>
+				<xs:documentation>Indicate that a stack operation will be performed with the value</xs:documentation></xs:annotation>
 			<xs:simpleType>
 				<xs:restriction base="xs:string">
-					<xs:enumeration value="pop"/>
-					<xs:enumeration value="push"/>
-					<xs:enumeration value="peek"/>
+					<xs:enumeration value="pop">
+						<xs:annotation>
+							<xs:documentation>The value will be popped from the stack</xs:documentation></xs:annotation></xs:enumeration>
+					<xs:enumeration value="push">
+						<xs:annotation>
+							<xs:documentation>The value will be pushed on a stack</xs:documentation></xs:annotation></xs:enumeration>
+					<xs:enumeration value="peek">
+						<xs:annotation>
+							<xs:documentation>The value will be peeked from the top of the stack, but it will stay there</xs:documentation></xs:annotation></xs:enumeration>
 				</xs:restriction>
 			</xs:simpleType>
 		</xs:attribute>
 		<xs:attribute name="forcedType">
+			<xs:annotation>
+				<xs:documentation>Indicate the desired type for the state value. If the value is not already of this type, a conversion will be attempted. The forcedType is used to convert values of event fields.</xs:documentation></xs:annotation>
 			<xs:simpleType>
 				<xs:restriction base="xs:string">
-					<xs:enumeration value="int" />
-					<xs:enumeration value="long" />
-					<xs:enumeration value="string" />
+					<xs:enumeration value="int" >
+						<xs:annotation>
+							<xs:documentation>The value should be an integer</xs:documentation></xs:annotation></xs:enumeration>
+					<xs:enumeration value="long" >
+						<xs:annotation>
+							<xs:documentation>The value should be a long</xs:documentation></xs:annotation></xs:enumeration>
+					<xs:enumeration value="string" >
+						<xs:annotation>
+							<xs:documentation>The value should be a double</xs:documentation></xs:annotation></xs:enumeration>
 				</xs:restriction>
 			</xs:simpleType>
 		</xs:attribute>
-		<xs:attribute name="value" type="xs:string" />
+		<xs:attribute name="value" type="xs:string" >
+			<xs:annotation>
+				<xs:documentation>Indicate what the value is. A value should be specified only if the type is int, long, string or event_field. See the documentation on types for information on what to put for value.</xs:documentation></xs:annotation></xs:attribute>
 	</xs:complexType>
 
 	<xs:complexType name="eventField">
-		<xs:attribute name="name" type="xs:string" use="required" />
+		<xs:annotation>
+			<xs:documentation>This element is used in conditions where the value of an event field is compared to something else. It is not the same as the stateAttribute's type eventField, where the eventField is used as the name for an attribute to the state system.</xs:documentation></xs:annotation>
+		<xs:attribute name="name" type="xs:string" use="required" >
+			<xs:annotation>
+				<xs:documentation>Indicate which field to use.</xs:documentation></xs:annotation></xs:attribute>
 	</xs:complexType>
 
-</xs:schema>
\ No newline at end of file
+</xs:schema>
diff --git a/lttng/org.eclipse.linuxtools.tmf.analysis.xml.core/src/org/eclipse/linuxtools/tmf/analysis/xml/core/module/xmlTimeGraphView.xsd b/lttng/org.eclipse.linuxtools.tmf.analysis.xml.core/src/org/eclipse/linuxtools/tmf/analysis/xml/core/module/xmlTimeGraphView.xsd
index 53f590356b..afd949520b 100644
--- a/lttng/org.eclipse.linuxtools.tmf.analysis.xml.core/src/org/eclipse/linuxtools/tmf/analysis/xml/core/module/xmlTimeGraphView.xsd
+++ b/lttng/org.eclipse.linuxtools.tmf.analysis.xml.core/src/org/eclipse/linuxtools/tmf/analysis/xml/core/module/xmlTimeGraphView.xsd
@@ -14,63 +14,119 @@
 	attributeFormDefault="unqualified" elementFormDefault="qualified">
 
 	<xs:complexType name="timeGraphView">
+		<xs:annotation>
+			<xs:documentation>Declares a data-driven time graph view, which defines how the view will display the results of an analysis. For now, only state system analysis are supported by this view.</xs:documentation></xs:annotation>
 		<xs:sequence>
-			<xs:element maxOccurs="1" minOccurs="0" name="head" type="headOutput" />
-			<xs:element maxOccurs="unbounded" minOccurs="0" name="definedValue" type="definedValue" />
-			<xs:element maxOccurs="unbounded" minOccurs="0" name="entry" type="viewEntry" />
+			<xs:element maxOccurs="1" minOccurs="0" name="head" type="headOutput" >
+				<xs:annotation>
+					<xs:documentation>Provider meta-information on this view, like labels and analysis it applies to.</xs:documentation></xs:annotation></xs:element>
+			<xs:element maxOccurs="unbounded" minOccurs="0" name="definedValue" type="definedValue" >
+				<xs:annotation>
+					<xs:documentation>Define a mapping between a human-readable text and the value used in the analysis. The "definedValue"'s optional "color" attribute is the color with which this value will be displayed.</xs:documentation></xs:annotation></xs:element>
+			<xs:element maxOccurs="unbounded" minOccurs="0" name="entry" type="viewEntry" >
+				<xs:annotation>
+					<xs:documentation>Define how to determine the entries (lines) to show on the time graph view. An entry may have children entry elements defined as children, where children are sub-elements of this one (for example, child attributes in the state system). A parent/child relationship may be defined for entries of the same level. See the viewEntry element documentation for more details.</xs:documentation></xs:annotation></xs:element>
 		</xs:sequence>
-		<xs:attribute name="id" type="xs:string" use="required" />
+		<xs:attribute name="id" type="xs:string" use="required" >
+			<xs:annotation>
+				<xs:documentation>The unique identifier of this view element. It will be used by the framework to identify this view.</xs:documentation></xs:annotation></xs:attribute>
 	</xs:complexType>
 
 	<xs:complexType name="headOutput">
+		<xs:annotation>
+			<xs:documentation>Declares the meta-information that can be defined for an XML time graph view.</xs:documentation></xs:annotation>
 		<xs:sequence>
 			<xs:element maxOccurs="unbounded" minOccurs="0" name="analysis">
+				<xs:annotation>
+					<xs:documentation>Indicate that the view applies to the analysis identified with the given ID. To have a view apply to an XML-defined state system analysis, you'd use the state provider ID in the "stateProvider" element.</xs:documentation></xs:annotation>
 				<xs:complexType>
-					<xs:attribute name="id" type="xs:string" use="required" />
-					<xs:attribute name="ssid" type="xs:string" use="optional" />
+					<xs:attribute name="id" type="xs:string" use="required" >
+						<xs:annotation>
+							<xs:documentation>The ID of the analysis this view applies to.</xs:documentation></xs:annotation></xs:attribute>
+					<xs:attribute name="ssid" type="xs:string" use="optional" >
+						<xs:annotation>
+							<xs:documentation>The ID of the state system this view applies to. The attribute is used only if the analysis contains more than one state system.</xs:documentation></xs:annotation></xs:attribute>
 				</xs:complexType>
 			</xs:element>
 			<xs:element maxOccurs="1" minOccurs="0" name="label">
+				<xs:annotation>
+					<xs:documentation>Add a label to the time graph view. If provided, this text will be displayed to the user to identify this view, otherwise, the view's ID will be used.</xs:documentation></xs:annotation>
 				<xs:complexType>
-					<xs:attribute name="value" use="required" />
+					<xs:attribute name="value" use="required" >
+						<xs:annotation>
+							<xs:documentation>The text used as a name for this time graph view.</xs:documentation></xs:annotation></xs:attribute>
 				</xs:complexType>
 			</xs:element>
 		</xs:sequence>
 	</xs:complexType>
 
 	<xs:complexType name="viewEntry">
+		<xs:annotation>
+			<xs:documentation>Define a path to entries in the view. If this element is at the top level, the base path to reach the entry is the root of the state system. Otherwise, it will use the parent element's corresponding attribute as the base. Each view entry element corresponds to a time graph view entry that will actually be displayed.</xs:documentation></xs:annotation>
 		<xs:sequence>
-			<xs:element maxOccurs="1" minOccurs="0" name="display" type="viewStateAttribute" />
-			<xs:element maxOccurs="1" minOccurs="0" name="id" type="viewStateAttribute" />
-			<xs:element maxOccurs="1" minOccurs="0" name="parent" type="viewStateAttribute" />
-			<xs:element maxOccurs="1" minOccurs="0" name="name" type="viewStateAttribute" />
-			<xs:element maxOccurs="unbounded" minOccurs="0" name="entry" type="viewEntry" />
+			<xs:element maxOccurs="1" minOccurs="0" name="display" type="viewStateAttribute" >
+				<xs:annotation>
+					<xs:documentation>Indicate the attribute whose value will be displayed in the time graph (the value that changes over time). If this element is not specified, no entry will be created for this element, and all other elements will be ignored.</xs:documentation></xs:annotation></xs:element>
+			<xs:element maxOccurs="1" minOccurs="0" name="id" type="viewStateAttribute" >
+				<xs:annotation>
+					<xs:documentation>Specify which attribute to use as ID for this entry. This ID will be used in the ID column in the view, and will also be used to build the tree if a parent element is specified. If this element is not present, the display attribute's name will be used as ID.</xs:documentation></xs:annotation></xs:element>
+			<xs:element maxOccurs="1" minOccurs="0" name="parent" type="viewStateAttribute" >
+				<xs:annotation>
+					<xs:documentation>Specify how to find the parent's ID of this entry. By default, the parent/child hierarchy is the same as defined in the timeGraphView element of the XML file. This element will add to this default parent/child relationship so that elements at the same XML-defined level can still have a relationship.</xs:documentation></xs:annotation></xs:element>
+			<xs:element maxOccurs="1" minOccurs="0" name="name" type="viewStateAttribute" >
+				<xs:annotation>
+					<xs:documentation>Specify how to find the name of this entry. Typically, the name will be human-readable. If not specified, the display attribute's name will be used as the name.</xs:documentation></xs:annotation></xs:element>
+			<xs:element maxOccurs="unbounded" minOccurs="0" name="entry" type="viewEntry" >
+				<xs:annotation>
+					<xs:documentation>Define child entries for this entry. Child entries will be shown as children of this entry (with or without additional parent/child relationship defined through the viewEntry element's "parent" element).</xs:documentation></xs:annotation></xs:element>
 		</xs:sequence>
-		<xs:attribute name="path" type="xs:string" use="required" />
+		<xs:attribute name="path" type="xs:string" use="required" >
+			<xs:annotation>
+				<xs:documentation>The path of the entry in the state system. Wildcards '*' may be used. For example, to display entries from all CPUs, the path could be "CPUs/*" and one entry will be created for each sub-attribute of the "CPUs" attribute. Each entry will be used as the base for all child elements, unless specified otherwise.</xs:documentation></xs:annotation></xs:attribute>
 	</xs:complexType>
 
 	<xs:complexType name="viewStateAttribute">
 		<xs:sequence>
-			<xs:element maxOccurs="unbounded" minOccurs="0" name="stateAttribute" type="stateAttribute" />
+			<xs:element maxOccurs="unbounded" minOccurs="0" name="stateAttribute" type="viewStateAttribute" >
+				<xs:annotation>
+					<xs:documentation>If the type is a "query", those stateAttribute elements describe the  elements of the query.</xs:documentation></xs:annotation></xs:element>
 		</xs:sequence>
 		<xs:attribute name="type" use="required">
+			<xs:annotation>
+				<xs:documentation>The type of path to this attribute. The value of the other attributes will depend on the selected type.</xs:documentation></xs:annotation>
 			<xs:simpleType>
 				<xs:restriction base="xs:string">
-					<xs:enumeration value="constant" />
-					<xs:enumeration value="location" />
-					<xs:enumeration value="query" />
-					<xs:enumeration value="self" />
+					<xs:enumeration value="constant" >
+						<xs:annotation>
+							<xs:documentation>This type identifies the state system attribute by a constant string. For instance, if the state system attribute to display is "Status", it would be a constant type with value "Status".</xs:documentation></xs:annotation></xs:enumeration>
+					<xs:enumeration value="location" >
+						<xs:annotation>
+							<xs:documentation>This type indicates that the path to the attribute is at the specified location. A location avoids having to write the full path to an attribute every time it is being used. The location itself is a sequence of stateAttribute elements. For example, if we previously defined a location named "Procname" for path "Threads/tid/Procname", we can use a stateAttribute of type location with "Procname" value.</xs:documentation></xs:annotation></xs:enumeration>
+					<xs:enumeration value="query" >
+						<xs:annotation>
+							<xs:documentation>This type indicates that the path to the attribute is the result of a query. If this type is selected, a sequence of stateAttribute elements needs to be specified for this viewStateAttribute. The result of the query is the attribute name of the current element. For example, if the attribute we want is the PID of the current process on CPU 0, that PID can be found through the query "CPUs/0/CurrentThread". The value of this attribute would be for example 1234, which is the attribute we are looking for.</xs:documentation></xs:annotation></xs:enumeration>
+					<xs:enumeration value="self" >
+						<xs:annotation>
+							<xs:documentation>This type indicates that the requested attribute is the attribute itself. For this attribute, the reference is always relative (setting it to absolute will be ignored).</xs:documentation></xs:annotation></xs:enumeration>
 				</xs:restriction>
 			</xs:simpleType>
 		</xs:attribute>
-		<xs:attribute name="value" type="xs:string" />
+		<xs:attribute name="value" type="xs:string" >
+			<xs:annotation>
+				<xs:documentation>The value of this state attribute. A value should be specified if the type is "constant" or "location".</xs:documentation></xs:annotation></xs:attribute>
 		<xs:attribute name="reference" use="optional" default="relative">
+			<xs:annotation>
+				<xs:documentation>Specify which state system attribute to use as the base to reach this path. It is either absolute or relative. By default, it is relative to the current entry.</xs:documentation></xs:annotation>
 			<xs:simpleType>
 				<xs:restriction base="xs:string">
-					<xs:enumeration value="relative" />
-					<xs:enumeration value="absolute" />
+					<xs:enumeration value="relative" >
+						<xs:annotation>
+							<xs:documentation>The path will be calculated starting from the entry under which this viewStateAttribute element is defined.</xs:documentation></xs:annotation></xs:enumeration>
+					<xs:enumeration value="absolute" >
+						<xs:annotation>
+							<xs:documentation>The path will be calculated starting from the root of the state system. That means that if the entry itself is one of "CPUs/*", we could reach another attribute from the root of the state system, like "Threads/tid".</xs:documentation></xs:annotation></xs:enumeration>
 				</xs:restriction>
 			</xs:simpleType>
 		</xs:attribute>
 	</xs:complexType>
-</xs:schema>
\ No newline at end of file
+</xs:schema>