add some basic documentation for statements, extend documentation

2007-11-29  Juerg Billeter  <j@bitron.ch>

	* doc/vala/Makefile.am, doc/vala/classes.xml, doc/vala/default.css,
	  doc/vala/delegates.xml, doc/vala/enums.xml, doc/vala/exceptions.xml,
	  doc/vala/expressions.xml, doc/vala/index.xml, doc/vala/interfaces.xml,
	  doc/vala/namespaces.xml, doc/vala/statements.xml,
	  doc/vala/structs.xml, doc/vala/types.xml, doc/vala/xhtml.xsl: add some
	  basic documentation for statements, extend documentation structure

svn path=/trunk/; revision=735

14 files changed, 207 insertions, 2 deletions

diff --git a/doc/vala/Makefile.am b/doc/vala/Makefile.am
index 66882683f..2c1a7bf10 100644
--- a/doc/vala/Makefile.am
+++ b/doc/vala/Makefile.am
@@ -11,6 +11,7 @@ chapter_data = \
 	interfaces.html \
 	enums.html \
 	delegates.html \
+	exceptions.html \
 	$(NULL)
 
 built_data = \
@@ -46,6 +47,7 @@ book_sources = \
 	interfaces.xml \
 	enums.xml \
 	delegates.xml \
+	exceptions.xml \
 	$(NULL)
 
 MOSTLYCLEANFILES = $(built_data)
diff --git a/doc/vala/classes.xml b/doc/vala/classes.xml
index 812bebbf7..85feab509 100644
--- a/doc/vala/classes.xml
+++ b/doc/vala/classes.xml
@@ -44,5 +44,21 @@ class NamespaceName.ClassName {
 	<class-member>
 }</blockcode>
 	</section>
+	<section id="fields">
+		<h>Fields</h>
+		<p>Documentation</p>
+	</section>
+	<section id="methods">
+		<h>Methods</h>
+		<p>Documentation</p>
+	</section>
+	<section id="properties">
+		<h>Properties</h>
+		<p>Documentation</p>
+	</section>
+	<section id="signals">
+		<h>Signals</h>
+		<p>Documentation</p>
+	</section>
 </section>
 
diff --git a/doc/vala/default.css b/doc/vala/default.css
index 756949b1c..b4dfc407d 100644
--- a/doc/vala/default.css
+++ b/doc/vala/default.css
@@ -63,3 +63,8 @@ pre {
 	margin: 0 2em 1em 2em;
 }
 
+blockquote {
+	font-style: italic;
+	white-space: pre;
+}
+
diff --git a/doc/vala/delegates.xml b/doc/vala/delegates.xml
index 0517ed965..4734e00c0 100644
--- a/doc/vala/delegates.xml
+++ b/doc/vala/delegates.xml
@@ -1,5 +1,9 @@
 <?xml version="1.0"?>
 <section id="delegates">
 	<h>Delegates</h>
+	<section id="declaration">
+		<h>Delegate declarations</h>
+		<p>Documentation</p>
+	</section>
 </section>
 
diff --git a/doc/vala/enums.xml b/doc/vala/enums.xml
index 5b136752d..357514619 100644
--- a/doc/vala/enums.xml
+++ b/doc/vala/enums.xml
@@ -1,5 +1,17 @@
 <?xml version="1.0"?>
 <section id="enums">
 	<h>Enums</h>
+	<section id="declaration">
+		<h>Enum declarations</h>
+		<p>Documentation</p>
+	</section>
+	<section id="members">
+		<h>Enum members</h>
+		<p>Documentation</p>
+	</section>
+	<section id="methods">
+		<h>Methods</h>
+		<p>Documentation</p>
+	</section>
 </section>
 
diff --git a/doc/vala/exceptions.xml b/doc/vala/exceptions.xml
new file mode 100644
index 000000000..377bc84d9
--- /dev/null
+++ b/doc/vala/exceptions.xml
@@ -0,0 +1,9 @@
+<?xml version="1.0"?>
+<section id="exceptions">
+	<h>Exceptions</h>
+	<section id="handling">
+		<h>Exception handling</h>
+		<p>Documentation</p>
+	</section>
+</section>
+
diff --git a/doc/vala/expressions.xml b/doc/vala/expressions.xml
index 95e937e38..e2a66ea61 100644
--- a/doc/vala/expressions.xml
+++ b/doc/vala/expressions.xml
@@ -1,5 +1,21 @@
 <?xml version="1.0"?>
 <section id="expressions">
 	<h>Expressions</h>
+	<section id="arithmetic">
+		<h>Arithmetic operations</h>
+		<p>Documentation</p>
+	</section>
+	<section id="relational">
+		<h>Relational operations</h>
+		<p>Documentation</p>
+	</section>
+	<section id="logical">
+		<h>Logical operations</h>
+		<p>Documentation</p>
+	</section>
+	<section id="assignments">
+		<h>Assignments</h>
+		<p>Documentation</p>
+	</section>
 </section>
 
diff --git a/doc/vala/index.xml b/doc/vala/index.xml
index 1a45706be..e93939f81 100644
--- a/doc/vala/index.xml
+++ b/doc/vala/index.xml
@@ -15,6 +15,7 @@
 		<xi:include href="interfaces.xml"/>
 		<xi:include href="enums.xml"/>
 		<xi:include href="delegates.xml"/>
+		<xi:include href="exceptions.xml"/>
 	</body>
 </html>
 
diff --git a/doc/vala/interfaces.xml b/doc/vala/interfaces.xml
index a6925117f..6f5f2baa2 100644
--- a/doc/vala/interfaces.xml
+++ b/doc/vala/interfaces.xml
@@ -1,5 +1,21 @@
 <?xml version="1.0"?>
 <section id="interfaces">
 	<h>Interfaces</h>
+	<section id="declaration">
+		<h>Interface declarations</h>
+		<p>Documentation</p>
+	</section>
+	<section id="methods">
+		<h>Methods</h>
+		<p>Documentation</p>
+	</section>
+	<section id="properties">
+		<h>Properties</h>
+		<p>Documentation</p>
+	</section>
+	<section id="signals">
+		<h>Signals</h>
+		<p>Documentation</p>
+	</section>
 </section>
 
diff --git a/doc/vala/namespaces.xml b/doc/vala/namespaces.xml
index da568ff55..683430d13 100644
--- a/doc/vala/namespaces.xml
+++ b/doc/vala/namespaces.xml
@@ -1,5 +1,9 @@
 <?xml version="1.0"?>
 <section id="namespaces">
 	<h>Namespaces</h>
+	<section id="declaration">
+		<h>Namespace declarations</h>
+		<p>Documentation</p>
+	</section>
 </section>
 
diff --git a/doc/vala/statements.xml b/doc/vala/statements.xml
index 421bc9478..ec124e1e4 100644
--- a/doc/vala/statements.xml
+++ b/doc/vala/statements.xml
@@ -1,5 +1,102 @@
 <?xml version="1.0"?>
 <section id="statements">
 	<h>Statements</h>
+	<section id="selection">
+		<h>Selection statements</h>
+		<p>The if statement selects a statement for execution based on the value of a boolean expression.</p>
+		<blockquote>
+if-statement:
+	if ( boolean-expression ) embedded-statement
+	if ( boolean-expression ) embedded-statement else embedded-statement
+		</blockquote>
+	</section>
+	<section id="iteration">
+		<h>Iteration statements</h>
+		<p>The while statement conditionally executes an embedded statement zero or more times.</p>
+		<blockquote>
+while-statement:
+	while ( boolean-expression ) embedded-statement
+		</blockquote>
+		<p>The do statement conditionally executes an embedded statement one or more times.</p>
+		<blockquote>
+do-statement:
+	do embedded-statement while ( boolean-expression ) ;
+		</blockquote>
+		<p>The for statement evaluates a sequence of initialization expressions and then, while a condition is true, repeatedly executes an embedded statement and evaluates a sequence of iteration expressions.</p>
+		<blockquote>
+for-statement:
+	for ( [for-initializer] ; [for-condition] ; [for-iterator] ) embedded-statement
+
+for-initializer:
+	local-variable-declaration
+	statement-expression-list
+
+for-condition:
+	boolean-expression
+
+for-iterator:
+	statement-expression-list
+
+statement-expression-list:
+	statement-expression
+	statement-expression-list , statement-expression
+		</blockquote>
+		<p>Within the embedded statement of a for statement, a break statement can be used to transfer control to the end point of the for statement (thus ending iteration of the embedded statement), and a continue statement can be used to transfer control to the end point of the embedded statement (thus executing another iteration of the for statement).</p>
+		<p>The foreach statement enumerates the elements of a collection, executing an embedded statement for each element of the collection.</p>
+		<blockquote>
+foreach-statement:
+	foreach ( type identifier in expression ) embedded-statement
+		</blockquote>
+	</section>
+	<section id="jump">
+		<h>Jump statements</h>
+		<p>The break statement exits the nearest enclosing switch, while, do, for, or foreach statement.</p>
+		<blockquote>
+break-statement:
+	break ;
+		</blockquote>
+		<p>The continue statement starts a new iterataion of the nearest enclosing while, do, for, or foreach statement.</p>
+		<blockquote>
+continue-statement:
+	continue ;
+		</blockquote>
+		<p>When multiple while, do, for, or foreach statements are nested within each other, a continue statement applies only to the innermost statement. If a continue statement is not eclosed by a while, do, for, or foreach statement, a compile-time error occurs.</p>
+		<p>The return statement returns control to the caller of the function member in which the return statement appears.</p>
+		<blockquote>
+return-statement:
+	return [expression] ;
+		</blockquote>
+		<p>The throw statement throws an exception.</p>
+		<blockquote>
+throw-statement:
+	throw expression ;
+		</blockquote>
+	</section>
+	<section id="try">
+		<h>Try statement</h>
+		<p>The try statement provides a mechanism for catching exceptions that occur during execution of a block. Furthermore, the try statement provides the ability to specify a block of code that is always executed when control leaves the try statement.</p>
+		<blockquote>
+try-statement:
+	try block catch-clauses
+	try block [catch-clauses] finally-clause
+
+catch-clauses:
+	specific-catch-clause
+	[specific-catch-clauses] general-catch-clause
+
+specific-catch-clause:
+	specific-catch-clause
+	specific-catch-clauses specific-catch-clause
+
+specific-catch-clause:
+	catch ( error-type identifier ) block
+
+general-catch-clause:
+	catch block
+
+finally-clause:
+	finally block
+		</blockquote>
+	</section>
 </section>
 
diff --git a/doc/vala/structs.xml b/doc/vala/structs.xml
index c3ef1cd7d..378cdea31 100644
--- a/doc/vala/structs.xml
+++ b/doc/vala/structs.xml
@@ -20,5 +20,17 @@ struct NamespaceName.StructName {
 	&lt;struct-member&gt;
 }</blockcode>
 	</section>
+	<section id="fields">
+		<h>Fields</h>
+		<p>Documentation</p>
+	</section>
+	<section id="methods">
+		<h>Methods</h>
+		<p>Documentation</p>
+	</section>
+	<section id="properties">
+		<h>Properties</h>
+		<p>Documentation</p>
+	</section>
 </section>
 
diff --git a/doc/vala/types.xml b/doc/vala/types.xml
index 3d6f44b37..75a554d3f 100644
--- a/doc/vala/types.xml
+++ b/doc/vala/types.xml
@@ -3,5 +3,13 @@
 	<h>Types</h>
 	<p>Vala supports two kinds of data types: value types and reference types. Value types include simple types (e.g. char, int, and float), enum types, and struct types. Reference types include class types, interface types, and array types.</p>
 	<p>Value types differ from reference types in that variables of the value types directly contain their data, whereas variables of the reference types store references to their data, the latter being known as objects. With reference types, it is possible for two variables to reference the same object, and thus possible for operations on one variable to affect the object referenced by the other variable. With value types, the variables each have their own copy of the data, and it is not possible for operations on one to affect the other.</p>
+	<section id="valuetypes">
+		<h>Value types</h>
+		<p>Documentation</p>
+	</section>
+	<section id="referencetypes">
+		<h>Reference types</h>
+		<p>Documentation</p>
+	</section>
 </section>
 
diff --git a/doc/vala/xhtml.xsl b/doc/vala/xhtml.xsl
index 4b6287899..006e29048 100644
--- a/doc/vala/xhtml.xsl
+++ b/doc/vala/xhtml.xsl
@@ -61,13 +61,13 @@
 		<h2><xsl:value-of select="text()"/></h2>
 	</xsl:template>
 	<xsl:template match="body/section/section">
-		<xsl:apply-templates select="h|p|div|blockcode|section"/>
+		<xsl:apply-templates select="h|p|div|blockcode|blockquote|section"/>
 	</xsl:template>
 	<xsl:template match="body/section/section/h">
 		<h3><xsl:value-of select="text()"/><a id="{../@id}"><xsl:text> </xsl:text></a></h3>
 	</xsl:template>
 	<xsl:template match="div[@role='note']">
-		<div class="note"><xsl:apply-templates select="h|p|blockcode"/></div>
+		<div class="note"><xsl:apply-templates select="h|p|blockcode|blockquote"/></div>
 	</xsl:template>
 	<xsl:template match="div/h">
 		<h4><xsl:value-of select="text()"/></h4>
@@ -81,5 +81,8 @@
 	<xsl:template match="blockcode">
 		<pre><xsl:value-of select="text()"/></pre>
 	</xsl:template>
+	<xsl:template match="blockquote">
+		<blockquote><xsl:value-of select="text()"/></blockquote>
+	</xsl:template>
 </xsl:stylesheet>