[vala/0.40] vala: Improve source documentation

[Rico Tzschichholz <ricotz src gnome org>]

commit 62454c7c601562dd7b834654f986033ace170bcc
Author: Rico Tzschichholz <ricotz ubuntu com>
Date:   Tue May 26 10:03:16 2020 +0200

    vala: Improve source documentation

 vala/valaaddressofexpression.vala         |  4 +++-
 vala/valaarraycreationexpression.vala     |  4 +++-
 vala/valabaseaccess.vala                  |  2 +-
 vala/valadeletestatement.vala             |  4 +++-
 vala/valaelementaccess.vala               |  4 +++-
 vala/valaenumvalue.vala                   |  2 +-
 vala/valaerrorcode.vala                   |  2 +-
 vala/valaforeachstatement.vala            |  5 +++--
 vala/valainterface.vala                   |  2 +-
 vala/valalambdaexpression.vala            |  5 +++--
 vala/valalockstatement.vala               | 10 ++++++----
 vala/valapointerindirection.vala          |  4 +++-
 vala/valareferencetransferexpression.vala |  4 +++-
 vala/valasliceexpression.vala             |  4 +++-
 vala/valaunlockstatement.vala             |  4 +++-
 vala/valayieldstatement.vala              |  1 -
 16 files changed, 40 insertions(+), 21 deletions(-)
---
diff --git a/vala/valaaddressofexpression.vala b/vala/valaaddressofexpression.vala
index 8d0f02645..ba52bbafc 100644
--- a/vala/valaaddressofexpression.vala
+++ b/vala/valaaddressofexpression.vala
@@ -23,7 +23,9 @@
 using GLib;
 
 /**
- * Represents an address-of expression in the source code, e.g. `&foo`.
+ * Represents an address-of expression.
+ *
+ * {{{ &foo }}}
  */
 public class Vala.AddressofExpression : Expression {
        /**
diff --git a/vala/valaarraycreationexpression.vala b/vala/valaarraycreationexpression.vala
index a3c021a86..965286add 100644
--- a/vala/valaarraycreationexpression.vala
+++ b/vala/valaarraycreationexpression.vala
@@ -25,7 +25,9 @@
 using GLib;
 
 /**
- * Represents an array creation expression e.g. {{{ new int[] {1,2,3} }}}.
+ * Represents an array creation expression.
+ *
+ * {{{ new int[] { 1, 2, 3 } }}}
  */
 public class Vala.ArrayCreationExpression : Expression {
        /**
diff --git a/vala/valabaseaccess.vala b/vala/valabaseaccess.vala
index c33d78652..78444f41a 100644
--- a/vala/valabaseaccess.vala
+++ b/vala/valabaseaccess.vala
@@ -22,7 +22,7 @@
 
 
 /**
- * Represents an access to base class members in the source code.
+ * Represents an access to base type member in the source code.
  */
 public class Vala.BaseAccess : Expression {
        /**
diff --git a/vala/valadeletestatement.vala b/vala/valadeletestatement.vala
index eb1d92150..8d8996725 100644
--- a/vala/valadeletestatement.vala
+++ b/vala/valadeletestatement.vala
@@ -21,7 +21,9 @@
  */
 
 /**
- * Represents a delete statement e.g. "delete a".
+ * Represents a delete statement.
+ *
+ * {{{ delete foo; }}}
  */
 public class Vala.DeleteStatement : CodeNode, Statement {
        /**
diff --git a/vala/valaelementaccess.vala b/vala/valaelementaccess.vala
index 25e06bd13..4ace7225a 100644
--- a/vala/valaelementaccess.vala
+++ b/vala/valaelementaccess.vala
@@ -25,7 +25,9 @@
 using GLib;
 
 /**
- * Represents an array access expression e.g. "a[1,2]".
+ * Represents an array access expression.
+ *
+ * {{{ foo[1,2] }}}
  */
 public class Vala.ElementAccess : Expression {
        /**
diff --git a/vala/valaenumvalue.vala b/vala/valaenumvalue.vala
index b4d27bf06..53317ad59 100644
--- a/vala/valaenumvalue.vala
+++ b/vala/valaenumvalue.vala
@@ -23,7 +23,7 @@
 using GLib;
 
 /**
- * Represents an enum member in the source code.
+ * Represents an enum value member in the source code.
  */
 public class Vala.EnumValue : Constant {
        /**
diff --git a/vala/valaerrorcode.vala b/vala/valaerrorcode.vala
index c03b2577a..2e5274a05 100644
--- a/vala/valaerrorcode.vala
+++ b/vala/valaerrorcode.vala
@@ -23,7 +23,7 @@
 using GLib;
 
 /**
- * Represents an enum member in the source code.
+ * Represents an error value member in the source code.
  */
 public class Vala.ErrorCode : TypeSymbol {
        /**
diff --git a/vala/valaforeachstatement.vala b/vala/valaforeachstatement.vala
index 836a67651..595dbc222 100644
--- a/vala/valaforeachstatement.vala
+++ b/vala/valaforeachstatement.vala
@@ -22,8 +22,9 @@
 
 
 /**
- * Represents a foreach statement in the source code. Foreach statements iterate
- * over the elements of a collection.
+ * Represents a foreach statement in the source code.
+ *
+ * Foreach statements iterate over the elements of a collection.
  */
 public class Vala.ForeachStatement : Block {
        /**
diff --git a/vala/valainterface.vala b/vala/valainterface.vala
index 016032400..5ee995135 100644
--- a/vala/valainterface.vala
+++ b/vala/valainterface.vala
@@ -23,7 +23,7 @@
 using GLib;
 
 /**
- * Represents a class declaration in the source code.
+ * Represents an interface declaration in the source code.
  */
 public class Vala.Interface : ObjectTypeSymbol {
        private List<DataType> prerequisites = new ArrayList<DataType> ();
diff --git a/vala/valalambdaexpression.vala b/vala/valalambdaexpression.vala
index 73770b44d..b3151d551 100644
--- a/vala/valalambdaexpression.vala
+++ b/vala/valalambdaexpression.vala
@@ -23,8 +23,9 @@
 using GLib;
 
 /**
- * Represents a lambda expression in the source code. Lambda expressions are
- * anonymous methods with implicitly typed parameters.
+ * Represents a lambda expression in the source code.
+ *
+ * Lambda expressions are anonymous methods with implicitly typed parameters.
  */
 public class Vala.LambdaExpression : Expression {
        private static int next_lambda_id = 0;
diff --git a/vala/valalockstatement.vala b/vala/valalockstatement.vala
index 8a0391e94..2990ee5ef 100644
--- a/vala/valalockstatement.vala
+++ b/vala/valalockstatement.vala
@@ -26,11 +26,13 @@
 using GLib;
 
 /**
- * Represents a lock statement e.g. {{{ lock (a); }}} or {{{ lock (a) { f(a); } }}}.
+ * Represents a lock statement.
  *
- * If the statement is empty, the mutex remains locked until a corresponding UnlockStatement
- * occurs. Otherwise it's translated into a try/finally statement which unlocks the mutex
- * after the block is finished.
+ * {{{ lock (foo); }}} or {{{ lock (foo) { ... } }}}
+ *
+ * If the statement is empty, the mutex remains locked until a corresponding
+ * {@link Vala.UnlockStatement} occurs. Otherwise it's translated into a
+ * try/finally statement which unlocks the mutex after the block is finished.
  */
 public class Vala.LockStatement : CodeNode, Statement {
        /**
diff --git a/vala/valapointerindirection.vala b/vala/valapointerindirection.vala
index 761bed675..3a126173f 100644
--- a/vala/valapointerindirection.vala
+++ b/vala/valapointerindirection.vala
@@ -22,7 +22,9 @@
 
 
 /**
- * Represents a pointer indirection in the source code, e.g. `*pointer`.
+ * Represents a pointer indirection.
+ *
+ * {{{ *foo }}}
  */
 public class Vala.PointerIndirection : Expression {
        /**
diff --git a/vala/valareferencetransferexpression.vala b/vala/valareferencetransferexpression.vala
index 1c25af7fb..f455446bf 100644
--- a/vala/valareferencetransferexpression.vala
+++ b/vala/valareferencetransferexpression.vala
@@ -22,7 +22,9 @@
 
 
 /**
- * Represents a reference transfer expression in the source code, e.g. `#foo`.
+ * Represents a reference transfer expression.
+ *
+ * {{{ (owned) foo }}}
  */
 public class Vala.ReferenceTransferExpression : Expression {
        /**
diff --git a/vala/valasliceexpression.vala b/vala/valasliceexpression.vala
index 6621b41d8..bc399c8fc 100644
--- a/vala/valasliceexpression.vala
+++ b/vala/valasliceexpression.vala
@@ -25,7 +25,9 @@
 using GLib;
 
 /**
- * Represents an array slice expression e.g "a[1:5]".
+ * Represents an array slice expression.
+ *
+ * {{{ foo[1:5] }}}
  */
 public class Vala.SliceExpression : Expression {
        public Expression container {
diff --git a/vala/valaunlockstatement.vala b/vala/valaunlockstatement.vala
index 98a769459..f66e2b972 100644
--- a/vala/valaunlockstatement.vala
+++ b/vala/valaunlockstatement.vala
@@ -22,7 +22,9 @@
  */
 
 /**
- * Represents an unlock statement e.g. {{{ unlock (a); }}}.
+ * Represents an unlock statement.
+ *
+ * {{{ unlock (foo); }}}
  */
 public class Vala.UnlockStatement : CodeNode, Statement {
        /**
diff --git a/vala/valayieldstatement.vala b/vala/valayieldstatement.vala
index 5b5a6f307..6c9740968 100644
--- a/vala/valayieldstatement.vala
+++ b/vala/valayieldstatement.vala
@@ -42,7 +42,6 @@ public class Vala.YieldStatement : CodeNode, Statement {
        /**
         * Creates a new yield statement.
         *
-        * @param yield_expression the yield expression
         * @param source_reference reference to source code
         * @return                 newly created yield statement
         */