[vala/0.48] vala: Improve source documentation

[Rico Tzschichholz <ricotz src gnome org>]

commit f3a819af86645ff00307b6559d5edec3bfff6c45
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 991596b22..a18614651 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 c4b9c7a60..654ef7704 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 68a3cb8f9..14258af14 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 40a8c196b..3e8d111ad 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 1352e6b03..e0129d2a7 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 3e3c57b37..525fb7d55 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 5159c2b3f..1ae237cf7 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 019003936..e46b379d1 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 9d4497131..f1c4ff803 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 e64d4a206..c9cc96e7c 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 5e99b9dc0..156194cb8 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 3363c30f5..dcc095bed 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 bb280c339..a11c6fc38 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 d60d5706c..b40d80057 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 91d8e7f9f..7148f3b74 100644
--- a/vala/valayieldstatement.vala
+++ b/vala/valayieldstatement.vala
@@ -27,7 +27,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
         */