Refacting the vala doc

source/tutorials/index.rst

@@ -3,6 +3,6 @@ Tutorials
 
 .. toctree::
    :maxdepth: 2
-   :glob:
 
-   *
+   programming-language
+   gui-programming

source/tutorials/programming-language/main/01-00-first-program.rst

@@ -8,49 +8,62 @@ Sadly predictable, but still:
 
 .. code-block:: vala
 
-   class Demo.HelloWorld : GLib.Object {
-       public static int main(string[] args) {
-           stdout.printf("Hello, World\n");
-           return 0;
-       }
-   }
+    void main() {
+        stdout.printf("Hello, World\n");
+    }
 
 Of course, that is a Vala *Hello World* program.  I expect you can recognise some parts of it well enough, but just to be thorough I shall go through it step by step.
 
 .. code-block:: vala
 
-   class Demo.HelloWorld : GLib.Object {
+   void main() {
 
 
-This line identifies the beginning of a class definition.  Classes in Vala are very similar in concept to other languages.  A class is basically a type of object, of which instances can be created, all having the same properties.  The implementation of classed types is taken care of by the *gobject* library, but details of this are not important for general usage.
+This is the start of a method definition.  A method is a function related to a type of object that can be executed on an object of that type.  The fact that this method is called ``main`` and has the signature it does means that Vala will recognise it as the entry point for the program. ``void`` is the return type of the method, which means that the method does not return any value.
 
-What is important to note is that this class is specifically described as being a subclass of *GLib.Object*.  This is because Vala allows other types of class, but in most cases, this is the sort that you want.  In fact, some language features of Vala are only allowed if your class is descended from GLib's *Object*.
-
-Other parts of this line show namespacing and fully qualified names, although these will be explained later.
 
 .. code-block:: vala
 
-   public static int main(string[] args) {
+   stdout.printf("Hello, World\n");
+
 
+This line instructs Vala to execute the method called *printf* of the *stdout* object, with the hello string as an argument.  In Vala, this is always the syntax you use to call a method on an object, or to access an object's data. ``\n`` is the escape sequence for a new line.
 
-This is the start of a method definition.  A method is a function related to a type of object that can be executed on an object of that type.  The static method means that the method can be called without possessing a particular instance of the type.  The fact that this method is called ``main`` and has the signature it does means that Vala will recognise it as the entry point for the program.
 
-The *main* method doesn't have to be defined inside a class.  However, if it is defined inside a class it must be ``static``.  It doesn't matter if it's ``public`` or ``private``.  The return type may be either ``int`` or ``void``.  With a ``void`` return type the program will implicitly terminate with exit code 0.  The string array parameter holding the command line arguments is optional.
+---------------
+
+there are several ways to write a ``main`` method in vala, here are the possible ones :
 
 .. code-block:: vala
+
+    void main () {
+    }
 
-   stdout.printf("Hello, World\n");
+    int main () {
+        return 0;
+    }
 
+    int main (string[] args) {
+        return 0;
+    }
 
-*stdout* is an object in the *GLib* namespace that Vala ensures you have access to whenever required.  This line instructs Vala to execute the method called *printf* of the *stdout* object, with the hello string as an argument.  In Vala, this is always the syntax you use to call a method on an object, or to access an object's data. ``\n`` is the escape sequence for a new line.
+    void main (string[] args) {
+    }
 
-.. code-block:: vala
+it is possible to declare your main in a class only if it is public and static.
+``int`` is the return type of the main method, which means that the method returns an integer value. The integer value returned by the main method is the exit status of the program. The exit status is a value returned by a program to the operating system. The operating system can then use this value to determine whether the program executed successfully or not. A return value of 0 indicates that the program executed successfully, while a non-zero value indicates that the program did not execute successfully.
+
+``string[] args`` is an array of strings that are passed to the program when it is executed. The first element of the array is the name of the program itself. The remaining elements are any arguments that are passed to the program when it is executed. The arguments are separated by spaces. For example, if you execute the program with the command ``./hello arg1 arg2``, then the array will contain the following elements:
 
-   return 0;
 
-``return`` is to return a value to the caller and terminate the execution of the *main* method which also terminates the execution of the program. The returned value of the *main* method is then taken as the exit code of the program.
+.. code-block:: vala
+
+    public class Main {
+        public static void main(string[] args) {
+            //...
+        }
+    }
 
-The last lines simply end the definitions of the method and class.
 
 Compile and Run
 ---------------

source/tutorials/programming-language/main/02-00-basics/02-04-data-types.rst

@@ -10,16 +10,60 @@ Value Types
 
 Vala supports a set of the simple types as most other languages do.
 
-* Byte, ``char``, ``uchar``; their names are *char* for historical reasons.
-* Character, ``unichar``; a 32-bit Unicode character
-* Integer, ``int``, ``uint``
-* Long Integer, ``long``, ``ulong``
-* Short Integer, ``short``, ``ushort``
-* Guaranteed-size Integer, ``int8``, ``int16``, ``int32``, ``int64`` as well as their unsigned siblings ``uint8``, ``uint16``, ``uint32``, ``uint64``. The numbers indicate the lengths in bits.
-* Float number, ``float``, ``double``
-* Boolean, ``bool``; possible values are ``true`` and ``false``
-* Compound, ``struct``
-* Enumeration, ``enum``; represented by integer values, not as classes like Java's enums
+.. list-table:: 
+   :widths: 10 18 10 50
+   :header-rows: 1
+
+   * - NameType
+     - Type
+     - Size
+     - Description
+   * - Byte
+     - char, uchar
+     - 1 byte
+     - Their names are "char" for historical reasons.
+   * - Character
+     - unichar
+     - 4 bytes
+     - 32-bit Unicode character
+   * - Integer
+     - int, uint
+     - 4 bytes
+     - Integer
+   * - Long Integer
+     - long, ulong
+     - 8 bytes
+     - Long integer
+   * - Short Integer
+     - short, ushort
+     - 2 bytes
+     - Short integer
+   * - Platform-Specific Integer 
+     - ssize_t, size_t
+     - Depend on platform
+     - Unsigned integer type, the size of which is platform-dependent
+   * - Guaranteed-size Integer
+     - int8, uint8, int16, uint16, int32, uint32, int64, uint64 
+     - 1, 2, 4, 8 bytes
+     - Integers of guaranteed sizes (8, 16, 32, 64 bits) and their unsigned versions
+   * - Float number
+     - float, double
+     - 4, 8 bytes
+     - Floating-point number
+   * - Boolean
+     - bool
+     - 1 byte
+     - Possible values: true and false
+   * - Compound
+     - struct
+     - Varies
+     - Compound type
+   * - Enumeration
+     - enum 
+     - 4 bytes (int)
+     - Represented by integer values, not as classes like Java's enums
+
+For more information on structs and enums, please refer to :doc:`02-07-language-elements`
 
 Here are some examples.
 
@@ -85,11 +129,14 @@ You can slice a string with ``[start:end]``.  Negative values represent position
    string s1 = greeting[7:12];        // => "world"
    string s2 = greeting[-4:-2];       // => "or"
 
-Note that indices in Vala start with 0 as in most other programming languages.  Starting with Vala 0.11 you can access a single byte of a string with ``[index]``:
+.. note::
+    that indices in Vala start with 0 as in most other programming languages
+
+you can access a single byte of a string with ``[index]``:
 
 .. code-block:: vala
 
-   uint8 b = greeting[7];             // => 0x77
+   uint8 b = greeting[7];            // => 119, the ASCII value of 'w'
 
 However, you cannot assign a new byte value to this position, since Vala strings are immutable.
 
@@ -103,16 +150,9 @@ Many of the basic types have reasonable methods for parsing from and converting
    string s1 = true.to_string();           // => "true"
    string s2 = 21.to_string();             // => "21"
 
-Two useful methods for writing and reading strings to/from the console (and for your first explorations with Vala) are *stdout.printf()* and *stdin.read_line()*:
-
-.. code-block:: vala
 
-   stdout.printf("Hello, world\n");
-   stdout.printf("%d %g %s\n", 42, 3.1415, "Vala");
-   string input = stdin.read_line();
-   int number = int.parse(stdin.read_line());
+If you want learn how print your string jump it :doc:`02-09-output-input`
 
-You already know *stdout.printf()* from the *Hello World* example.  Actually, it can take an arbitrary number of arguments of different types, whereas the first argument is a *format string*, following the same rules as `C format strings <http://en.wikipedia.org/wiki/Printf>`_. If you must output an error message you can use *stderr.printf()* instead of *stdout.printf()*.
 
 In addition the *in* operation can be used to determine whether one string contains another, e.g.
 
@@ -271,7 +311,6 @@ Defining a new type is a matter of derive it from the one you need. Here is an e
 .. code-block:: vala
 
    /* defining an alias for a basic type (equivalent to typedef int Integer in C)*/
-   [SimpleType]
    public struct Integer : uint {
    }
 

source/tutorials/programming-language/main/02-00-basics/02-07-language-elements.rst

@@ -115,7 +115,7 @@ Delegates may also be created locally. A member method can also be assigned to a
 
 More samples in `Delegates Manual <https://wiki.gnome.org/Projects/Vala/Manual/Delegates>`_.
 
-Anonymous Methods / Closures
+Anonymous Methods / Closures (lambda expressions)
 ----------------------------
 
 .. code-block:: vala
@@ -217,14 +217,15 @@ Structs
        public int a;
    }
 
-defines a `struct` type, i.e. a compound value type.  A Vala struct may have methods in a limited way and also may have private members, meaning the explicit `public` access modifier is required.
+defines a `struct` type, i.e. a compound value type.  A Vala struct may have methods in a limited way and also may have private members
+``public`` keyword is optional and can be omitted. however, one method can be private or public.
 
 .. code-block:: vala
 
    struct Color {
-       public double red;
-       public double green;
-       public double blue;
+       double red;
+       double green;
+       double blue;
    }
 
 This is how you can initialise a struct:
@@ -248,10 +249,124 @@ This is how you can initialise a struct:
        blue = 1.0
    };
 
+Structs can have methods: 
+
+.. code-block:: vala
+
+   struct Point {
+       public double x;
+       public double y;
+
+       public double distance_to(Point other) {
+           return Math.sqrt((x - other.x) * (x - other.x) + (y - other.y) * (y - other.y));
+       }
+   }
+
+   void main() {
+       Point p1 = { 1.0, 2.0 };
+       Point p2 = { 4.0, 6.0 };
+
+       p1.distance_to(p2);  // returns 5.0
+   }
+
 Structs are stack/inline allocated and copied on assignment.
 
 To define an array of structs, please see the `FAQ <faq#how-do-i-create-an-array-of-structs>`_
 
+
+Enums
+-----
+
+Enums are a way to define a set of named integer constants.  They are useful for defining a set of related values that are not necessarily sequential.  For example, the following code defines an enum named *EnumName* with three values:
+
+.. code-block:: vala
+
+   enum EnumName {
+       VALUE1,
+       VALUE2,
+       VALUE3
+   }
+
+The values of the enum are accessed by the name of the enum followed by a period and the name of the value, e.g. *EnumName.VALUE1*.
+
+
+An enum can contains functions:
+
+.. code-block:: vala
+
+    enum EnumName {
+        VALUE1,
+        VALUE2,
+        VALUE3;
+
+        public unowned string to_string() {
+            switch (this) {
+                case VALUE1: return "Value 1";
+                case VALUE2: return "Value 2";
+                case VALUE3: return "Value 3";
+                default: return "Unknown";
+            }
+        }
+    }
+
+    void main() {
+        print(EnumName.VALUE1.to_string());  // prints "Value 1"
+        print(EnumName.VALUE2.to_string());  // prints "Value 2"
+        print(EnumName.VALUE3.to_string());  // prints "Value 3"
+    }
+
+
+.. note::
+    an enum can be set in a class
+
+Flags
+-----
+
+Enums can be used like flags by using the `[Flags]` attribute on the enum definition.
+This allows you to combine the values using the `+` operator and check if a value is set using the `in` operator.
+
+For example:
+
+.. code-block:: vala
+
+    [Flags]
+    enum MyFlags {
+        FLAG1,
+        FLAG2,
+        FLAG3
+    }
+
+    void main() {
+        MyFlags flags;
+
+        flags = MyFlags.FLAG1 + MyFlags.FLAG3;
+
+        if (MyFlags.FLAG1 in flags)
+            print("FLAG1 is set");
+        if (MyFlags.FLAG2 in flags)
+            print("FLAG2 is set");
+        if (MyFlags.FLAG3 in flags)
+            print("FLAG3 is set");
+    }
+
+.. list-table:: Operators for Enumerations (Flags)
+   :widths: 10 70
+   :header-rows: 1
+
+   * - Operator
+     - Description
+   * - ``+=``
+     - Adds flags to this
+   * - ``-=``
+     - Removes flags from this
+   * - ``+``
+     - Combines two flags.
+   * - ``-``
+     - Subtracts the flags.
+   * - ``in``
+     - Checks if a flag is set. 
+
+
 Classes
 -------
 
@@ -262,6 +377,8 @@ Classes
 
 Defines a class, i.e. a reference type. In contrast to structs, instances of classes are heap allocated. There is much more syntax related to classes, which is discussed more fully in the section about object oriented programming.
 
+:doc:`../03-00-object-oriented-programming` and  :doc:`../03-00-object-oriented-programming/03-01-basics`
+
 Interfaces
 ----------