Port Vala for Java Programmers Developer Guide

docs/.vitepress/config.js

@@ -813,6 +813,44 @@ export default {
                                 link: '/developer-guides/documentation',
                                 collapsed: true,
                                 items: [
+                                        {
+                                        text: 'Valadoc Guide',
+                                        link: '/developer-guides/documentation/valadoc-guide',
+                                        collapsed: true,
+                                        items: [
+                                            {
+                                                text: '1. Quick Start',
+                                                link: '/developer-guides/documentation/valadoc-guide/01-00-quick-start'
+                                            },
+                                            {
+                                                text: '2. Command Line Tool',
+                                                link: '/developer-guides/documentation/valadoc-guide/02-00-command-line-tool'
+                                            },
+                                            {
+                                                text: '3. Documentation Comment Markup',
+                                                link: '/developer-guides/documentation/valadoc-guide/03-00-documentation-comment-markup',
+                                                collapsed: true,
+                                                items: [
+                                                    {
+                                                        text: '3.1.1. Brief Description',
+                                                        link: '/developer-guides/documentation/valadoc-guide/03-00-documentation-comment-markup/03-01-brief-description'
+                                                    },
+                                                    {
+                                                        text: '3.1.2. Formatting',
+                                                        link: '/developer-guides/documentation/valadoc-guide/03-00-documentation-comment-markup/03-02-formatting'
+                                                    },
+                                                    {
+                                                        text: '3.1.3. Taglets',
+                                                        link: '/developer-guides/documentation/valadoc-guide/03-00-documentation-comment-markup/03-03-taglets'
+                                                    },
+                                                    {
+                                                        text: '3.1.4. Contributing to Valadoc',
+                                                        link: '/developer-guides/documentation/valadoc-guide/03-00-documentation-comment-markup/03-04-contributing-to-valadoc'
+                                                    }
+                                                ]
+                                            }
+                                        ]
+                                    },
                                     {
                                         text: 'Vala for C# Programmers',
                                         link: '/developer-guides/documentation/vala-for-csharp-devs',
@@ -973,43 +1011,52 @@ export default {
                                         ]
                                     },
                                     {
-                                        text: 'Valadoc Guide',
-                                        link: '/developer-guides/documentation/valadoc-guide',
+                                        text: 'Vala for Java Programmers',
+                                        link: '/developer-guides/documentation/vala-for-java-devs',
                                         collapsed: true,
                                         items: [
                                             {
-                                                text: '1. Quick Start',
-                                                link: '/developer-guides/documentation/valadoc-guide/01-00-quick-start'
+                                                text: 'Source File and Compilation',
+                                                link: '/developer-guides/documentation/vala-for-java-devs/01-source-file-and-compilation'
                                             },
                                             {
-                                                text: '2. Command Line Tool',
-                                                link: '/developer-guides/documentation/valadoc-guide/02-00-command-line-tool'
+                                                text: 'Simple Data Types',
+                                                link: '/developer-guides/documentation/vala-for-java-devs/02-simple-data-types'
                                             },
                                             {
-                                                text: '3. Documentation Comment Markup',
-                                                link: '/developer-guides/documentation/valadoc-guide/03-00-documentation-comment-markup',
-                                                collapsed: true,
-                                                items: [
-                                                    {
-                                                        text: '3.1.1. Brief Description',
-                                                        link: '/developer-guides/documentation/valadoc-guide/03-00-documentation-comment-markup/03-01-brief-description'
-                                                    },
-                                                    {
-                                                        text: '3.1.2. Formatting',
-                                                        link: '/developer-guides/documentation/valadoc-guide/03-00-documentation-comment-markup/03-02-formatting'
-                                                    },
-                                                    {
-                                                        text: '3.1.3. Taglets',
-                                                        link: '/developer-guides/documentation/valadoc-guide/03-00-documentation-comment-markup/03-03-taglets'
-                                                    },
-                                                    {
-                                                        text: '3.1.4. Contributing to Valadoc',
-                                                        link: '/developer-guides/documentation/valadoc-guide/03-00-documentation-comment-markup/03-04-contributing-to-valadoc'
-                                                    }
-                                                ]
-                                            }
+                                                text: 'Strings',
+                                                link: '/developer-guides/documentation/vala-for-java-devs/03-strings'
+                                            },
+                                            {
+                                                text: 'Arrays',
+                                                link: '/developer-guides/documentation/vala-for-java-devs/04-arrays'
+                                            },
+                                            {
+                                                text: 'Naming Conventions',
+                                                link: '/developer-guides/documentation/vala-for-java-devs/05-naming-conventions'
+                                            },
+                                            {
+                                                text: 'Foreach',
+                                                link: '/developer-guides/documentation/vala-for-java-devs/06-foreach'
+                                            },
+                                            {
+                                                text: 'Inheritance',
+                                                link: '/developer-guides/documentation/vala-for-java-devs/07-inheritance'
+                                            },
+                                            {
+                                                text: 'Methods',
+                                                link: '/developer-guides/documentation/vala-for-java-devs/08-methods'
+                                            },
+                                            {
+                                                text: 'Type Inference',
+                                                link: '/developer-guides/documentation/vala-for-java-devs/09-type-inference'
+                                            },
+                                            {
+                                                text: 'Code Organisation',
+                                                link: '/developer-guides/documentation/vala-for-java-devs/10-code-organisation'
+                                            },
                                         ]
-                                    }
+                                    },
                                 ]
                             },
                             {

docs/developer-guides/documentation/vala-for-java-devs.md

@@ -0,0 +1,25 @@
+# Vala for Java Developers
+
+Vala is an object-oriented programming language with a syntax that is
+very similar to Java. As a Java developer, you will find many familiar
+concepts and constructs in Vala, making it easier to learn and
+transition to this language.
+
+Despite these similarities, there are also some differences between Vala
+and Java, such as Vala\'s use of reference counting for memory
+management instead of garbage collection..
+
+Throughout this guide, we will explore the similarities and differences
+between Vala and Java, helping you leverage your Java knowledge to
+quickly become proficient in Vala programming.
+
+#### [Source File and Compilation](vala-for-java-devs/01-source-file-and-compilation)
+#### [Simple Data Types](vala-for-java-devs/02-simple-data-types)
+#### [Strings](vala-for-java-devs/03-strings)
+#### [Arrays](vala-for-java-devs/04-arrays)
+#### [Naming Conventions](vala-for-java-devs/05-naming-conventions)
+#### [Foreach](vala-for-java-devs/06-foreach)
+#### [Inheritance](vala-for-java-devs/07-inheritance)
+#### [Methods](vala-for-java-devs/08-methods)
+#### [Type Inference](vala-for-java-devs/09-type-inference)
+#### [Code Organization](vala-for-java-devs/10-code-corganization)  

docs/developer-guides/documentation/vala-for-java-devs/01-source-file-and-compilation.md

@@ -0,0 +1,79 @@
+# Source File and Compilation
+
+## Source Files
+
+Java: `*.java`
+
+Vala: `*.vala`
+
+## Compilation
+
+Java: compiled to JVM byte code (`.class` files)
+
+``` bash
+$ javac SourceFile1.java SourceFile2.java
+```
+
+Vala: compiled to native code via C code as intermediate code
+
+``` bash
+$ valac source1.vala source2.vala -o program
+```
+
+Vala's standard object system is GObject, compiled Vala libraries are
+valid C libraries.
+
+## Using Libraries
+
+Java: `.jar` files
+
+``` bash
+$ javac -classpath foo-1.0.jar;bar-3.0.jar SourceFile.java
+```
+
+Vala: packages (C libraries with `.vapi` files)
+
+``` bash
+$ valac --pkg foo-1.0 --pkg bar-3.0 source.vala
+```
+
+Java:
+
+``` java
+import javax.swing.*;
+
+package org.foo.bar;
+
+// ...
+```
+
+Vala: namespaces, not related to directory hierarchy, no reverse domain
+name scheme
+
+``` vala
+using Gtk;
+
+namespace Foo.Bar {
+    // ...
+}
+```
+
+Vala namespaces may contain methods without classes. They are implicitly
+static.
+
+## Default Import
+
+Java: package `java.lang.*` imported by default
+
+Vala: namespace `GLib` imported by default
+
+## Main Entry Point
+
+Java: `public static void main(String[] args)`
+
+Vala: `static int main (string[] args)`
+
+May be outside a class, may be private, may return `int` (exit code),
+`args` argument is optional
+
+INSERT IMAGE HERE

docs/developer-guides/documentation/vala-for-java-devs/02-simple-data-types.md

@@ -0,0 +1,52 @@
+# Simple Data Types
+
+## Basic Types
+
+In Vala, the sizes of standard types (`int`, `long`, etc.) are
+architecture-dependent. To get the size of a type in bytes, you can use
+the `sizeof` operator. For example:
+
+```vala
+int size = sizeof (int);
+```
+
+Vala provides additional types with architecture-independent guaranteed
+sizes:
+
+- Signed: `int8`, `int16`, `int32`, `int64`
+- Unsigned: `uint8`, `uint16`, `uint32`, `uint64`
+
+Note that there is no `byte` type in Vala. Instead, you can use `uint8`
+or `int8`.
+
+Vala uses `bool` instead of `boolean` for boolean values.
+
+Vala also has an additional basic type called `unichar`, which
+represents a Unicode character.
+
+## Constant Modifier
+
+In Vala, the `const` keyword is used to declare constants, similar to
+`final` in Java.
+
+## Methods on Basic Types
+
+Vala\'s basic types have methods that can be called directly on the
+values. For example:
+
+``` vala
+int a = (-4).abs ();
+string s = a.to_string ();
+int b = int.max (5, 7);      // static method call on 'int'
+```
+
+In the above code:
+
+- `(-4).abs ()` calls the `abs` method on the integer value `-4`,
+  returning its absolute value.
+- `a.to_string ()` converts the integer `a` to a string representation.
+- `int.max (5, 7)` calls the static `max` method on the `int` type,
+  returning the maximum value between `5` and `7`.
+
+These are just a few examples of the methods available on Vala\'s basic
+types.

docs/developer-guides/documentation/vala-for-java-devs/03-strings.md

@@ -0,0 +1,31 @@
+# Strings
+
+| Java                             | Vala                           |
+| -------------------------------- | ------------------------------ |
+| Data type: String                | Data type: string (lower case) |
+| Equality test: str1.equals(str2) | Equality test: str1 == str2    |
+
+String comparisons compare content, not reference. You can compare
+strings lexicographically with `<`, `>`, `<=`, `>=` etc. Strings can be
+used with switch.
+
+Vala strings are UTF-8 encoded.
+
+Vala supports verbatim strings: `"""..."""`
+
+```vala
+string verbatim = """Verbatim strings don't evaluate escape sequences
+like \n, \t, ... and may span multiple lines.
+The line breaks are part of the string.
+You can use quotation marks (") and backslashes (\)
+inside a verbatim string without escaping them.""";
+```
+
+Vala supports string templates: `@"..."`. String templates may contain
+expressions, prefixed by a `$` sign.
+
+```vala
+string name = "John";
+stdout.printf (@"Welcome, $name!");
+stdout.printf (@"3 + 2 = $(3 + 2)");
+```

docs/developer-guides/documentation/vala-for-java-devs/04-arrays.md

@@ -0,0 +1,42 @@
+# Arrays
+
+## Dynamic Growth
+
+You can add elements to arrays dynamically by using the `+=` operator.
+The array will be reallocated with sizes of powers of two:
+
+``` vala
+int[] squares = {};
+for (int i = 0; i < 100; i++) {
+    squares += i * i;
+}
+```
+
+## No Boundary Checking
+
+However, there is no runtime boundary checking for arrays in Vala:
+
+``` vala
+int[] a = new int[10];
+a[20] = 1;  // not safe!
+```
+
+(Optional boundary checking is planned for a future version of Vala.)
+
+## Multi-Dimensional Arrays
+
+Java: jagged multi-dimensional arrays `[][]` (arrays of arrays)
+
+``` java
+int[][] matrix = new int[3][];
+for (int[] row : matrix) {
+    row = new int[4];
+}
+```
+
+Vala: rectangular multi-dimensional arrays `[,]`, `[,,]`, etc.
+(allocated as one contiguous memory block), jagged array support planned
+
+``` vala
+int[,] matrix = new int[3,4];
+```