docs: translation of sample programs

samples/arthimetic-operators.kin

@@ -4,15 +4,15 @@
 
 
 
-#arthimetic operators in kin-lang
+#   Arthimetic operators in kin-lang
 
-reka num1 = 100;
-reka num2 = 200;
+reka num1 = 100;                # num1 decralation and assigning.
+reka num2 = 200;                # num2 decralation and assigning
 
-reka product = num1 * num2;
-reka difference = num2 - num1;
-reka sum = num2 + num1;
-reka quotient = num1 / num2;
-reka reminder = num2 % num1;
+reka product = num1 * num2;     # product variable decralation and assigning
+reka difference = num2 - num1;  # product variable decralation and assigning
+reka sum = num2 + num1;         # product variable decralation and assigning
+reka quotient = num1 / num2;    # quotient variable decralation and assigning
+reka reminder = num2 % num1;    # reminder variable decralation and assigning
 
-tangaza_amakuru ` product: ${product}, difference: ${difference}, sum: ${sum}, quotient: ${quotient}, reminder: ${reminder}`;
+tangaza_amakuru ` product: ${product}, difference: ${difference}, sum: ${sum}, quotient: ${quotient}, reminder: ${reminder}`; # Logging data to the std.

samples/comments.kin

@@ -4,6 +4,6 @@
 
 
 
-# this is comment in kin-lang
+# Comment in Kin
 
-tangaza_amakuru `comments are ignored while tokenizing`;
+tangaza_amakuru `comments are ignored while tokenizing`; # Loggin information to the std.

samples/data-types.kin

@@ -3,22 +3,22 @@
 #   LICENSE file in the root directory of this source tree.
 
 
-#data-types in kin-lang
+#  Datatypes in Kin
 
 
-reka umubare1 = 10;
-reka umubare_wibice1 = 10.1;
-reka ukuri1 = nibyo;
-reka urutonde_amagambo = ['Ibigori', 'Umuceri', 'Ibindi'];
-reka urutonde_imibare = [100, 133, 1, 0, 4.6];
-reka urutonde_ruvanze = [100, "Ibigori", 1.2];
-reka ijambo = "umuntu";
-reka amafaranga = ubusa;
+reka umubare1 = 10;  # variable (number) umubare1 decralation and assigning
+reka umubare_wibice1 = 10.1;  # variable (number) umubare_wibice1 decralation and assigning
+reka ukuri1 = nibyo; # variable (number) ukuri1 decralation and assigning
+reka urutonde_amagambo = ['Ibigori', 'Umuceri', 'Ibindi'];  # variable (list of words) urutonde_amagambo decralation and assigning
+reka urutonde_imibare = [100, 133, 1, 0, 4.6];  # variable (list of numbers) urutonde_imibare decralation and assigning
+reka urutonde_ruvanze = [100, "Ibigori", 1.2];  # variable (list of both numbers and numbers) urutonde_ruvanze  decralation and assigning
+reka ijambo = "umuntu"; # variable (string) ijambo decralation and assigning
+reka amafaranga = ubusa;   # variable (null) amafaranga decralation and assigning
 reka umuntu = {
    amazina: "MURANGWA Pacifique",
    imyaka: 19,
    indeshyo: 187
-};
+}; # variable (structure) umuntu decralation and assigning
 
 tangaza_amakuru `
    ${ubwoko(umubare)}
@@ -27,4 +27,4 @@ tangaza_amakuru `
    ${ubwoko(urutonde)}
    ${ubwoko(ijambo)}
    ${ubwoko(amafaranga)}
-`;
+`; # Logging decralation && assigned variables to the std.

samples/exit.kin

@@ -3,15 +3,15 @@
 #   LICENSE file in the root directory of this source tree.
 
 
-# exiting kin program without completing execution.
+# exiting Kin program
 
 
-reka number = 10;
-reka users_number = injiza_amakuru `Umubare: `;
+reka number = 10;                                                   # variable (number) number decralation and assigining.
+reka users_number = injiza_amakuru `Umubare: `;                     # variable (users_number) users_number decralation and assigining.
 
-niba (users_number > number) {
-    tangaza_amakuru `Uratsinzwe wanditse umubare muto`;
-    kin_hagarara(1); # here we have one but 0 is also supported. it's used to indicate that program exited but there was no error.
+niba (users_number > number) {                                      # Check if the users_number is greater than number
+    tangaza_amakuru `Uratsinzwe wanditse umubare muto`;             # Loggin' information to the screen
+    kin_hagarara(1);                                                # here we have one but 0 is also supported. it's used to indicate that program exited but there was no error. # Exiting Kin but with an error from user. Case kin_hagarara(0); means that there is no error
 }
 
-tangaza_amakuru `Uratsinzzzeeeee wanditse umubare uruta uwacu.`;
+tangaza_amakuru `Uratsinzzzeeeee wanditse umubare uruta uwacu.`;    # Loggin' information to the std

samples/file-operations.kin

@@ -3,10 +3,12 @@
 #   LICENSE file in the root directory of this source tree.
 
 
-# file-operations in Kin
+# File Operations in Kin
 
 
-reka amakuru_ari_munyandiko = soma_inyandiko `path-to-file`; # reading a file.
-reka amakuru_ajya_munyandiko = injiza_amakuru `Amakuru ushaka gushyira munyandiko:`; # getting user's data that will be written to file.
-andika_inyandiko `path-to-file`; # writing to file
-vugurura_inyandiko `path-to-file , ${amakuru_ajya_munyandiko}`; # updating information in the file
+reka amakuru_ari_munyandiko = soma_inyandiko `path-to-file`;                            # reading a file.
+reka amakuru_ajya_munyandiko = injiza_amakuru `Amakuru ushaka gushyira munyandiko:`;    # getting user's data that will be written to file.
+andika_inyandiko `path-to-file`;                                                        # writing to file
+
+reka amakuru_ajya_munyandiko = "amakuru mashya";                                        # decralation of amakuru_ajya_munyandiko which will hold new information to be appended to a file
+vugurura_inyandiko `path-to-file , ${amakuru_ajya_munyandiko}`;                         # updating information in the file

samples/functions.kin

@@ -2,14 +2,14 @@
 #   This source code is licensed under the Apache License 2.0 found in the
 #   LICENSE file in the root directory of this source tree.
 
-# functions in kin-lang
+# Functions in Kin
 
-porogaramu_ntoya multiply_by_2(num) {
-    tanga num * 2;
+porogaramu_ntoya multiply_by_2(num) {           # multiply_by_2 function decralation
+    tanga num * 2;                              # return a given number multiplied by 2
 }
 
 
-reka umubare1 = 10;
-reka ibisubizo = multiply_by_2(umubare1);
+reka umubare1 = 10;                             # decralation of umubare1 variable to hold initial value of a number
+reka ibisubizo = multiply_by_2(umubare1);       # decralation and call of multiply_by_2 function which returns umubare1 multiplied by 2.
 
-tangaza_amakuru `${ibisubizo}`;
+tangaza_amakuru `${ibisubizo}`;                 # Loggin ibisubizo to the screen

samples/if-statements.kin

@@ -3,16 +3,16 @@
 #   LICENSE file in the root directory of this source tree.
 
 
-# if-statements in kin-lang
+# If statements in Kin
 
-reka i = injiza_amakuru `Duhe umubare: `;
+reka i = injiza_amakuru `Duhe umubare: `;   # ask a user to enter a number and then storing it in i variable
 
-niba ((i%3 == 0) && (i%5 == 0)) {
-    tangaza_amakuru `FizzBuzz`;
-}nanone_niba (i%3 == 0) {
-    tangaza_amakuru `Buzz`;
-}nanone_niba (i%5 == 0) {
-    tangaza_amakuru `Fizz`;
-}niba_byanze {
-    tangaza_amakuru `${i}`;
+niba ((i%3 == 0) && (i%5 == 0)) {           # check if i%3 == 0 and i%5 == 0 
+    tangaza_amakuru `FizzBuzz`;             # Log FizzBuzz if (i%3 == 0 and i%5 == 0)  is true
+}nanone_niba (i%3 == 0) {                   # Check if i%3 == 0
+    tangaza_amakuru `Buzz`;                 # Log Buzz if i%3 == 0
+}nanone_niba (i%5 == 0) {                   # Check if i%5 == 0
+    tangaza_amakuru `Fizz`;                 # Log Fizz if i%5 == 0
+}niba_byanze {                              # If all if statements fails
+    tangaza_amakuru `${i}`;                 # Log i to the std
 }

samples/loop-control-statements.kin

@@ -3,21 +3,22 @@
 #   LICENSE file in the root directory of this source tree.
 
 
-# loops control statements in kin-lang
+# Loops control statements in Kin
 
-reka i = 0;
 
-niba (i<100) subiramo {
+reka i = 0;                                 # Variable i decralation and assigining
 
-    niba ((i%3 == 0) && (i%5 == 0)) {
-        komeza;
-    }nanone_niba ((i%3) == 0) {
-        tangaza_amakuru `${i}`;
-    }nanone_niba ((i%5 == 0) && (i>90)) {
-        hagarara;
-    }niba_byanze {
+niba (i<100) subiramo {                     # Check if i<100 if not repeat the codes in the block
+
+    niba ((i%3 == 0) && (i%5 == 0)) {       # Check if ((i%3 == 0) && (i%5 == 0)) is true
+        komeza;                             # If ((i%3 == 0) && (i%5 == 0)) was true continue
+    }nanone_niba ((i%3) == 0) {             # Check again if ((i%3) == 0) is true
+        tangaza_amakuru `${i}`;             # Log i to the std, if ((i%3) == 0) was true
+    }nanone_niba ((i%5 == 0) && (i>90)) {   # Check again if ((i%5 == 0) && (i>90)) is true
+        hagarara;                           # stod the loop if ((i%5 == 0) && (i>90)) was true
+    }niba_byanze {                          # if all cases failed log i
         tangaza_amakuru `${i}`;
     }
 
-    i++;
+    i++;                                    # increment the value of i
 }

samples/loops.kin

@@ -2,11 +2,11 @@
 #   This source code is licensed under the Apache License 2.0 found in the
 #   LICENSE file in the root directory of this source tree.
 
-# simple loop in kin-lang
+# Loop in Kin
 
-reka i = 0;
+reka i = 0;                     # Declare variable i and assign it
 
-niba (i<10) subiramo {
-    tangaza_amakuru `${i}`;
-    i = i+1;
+niba (i<10) subiramo {          # Check if i<10,  if yes repeat the code in block, if no stop the loop
+    tangaza_amakuru `${i}`;     # Log i
+    i = i+1;                    # Increment i
 }

samples/miscellaneous-operators.kin

@@ -4,9 +4,10 @@
 
 
 
-# pointers in kin-lang
+# Pointers in Kin
 
-reka izina = "MURANGWA Pacifique";
-reka *aho_izina_ribitse = &izina;
+reka izina = "MURANGWA Pacifique";                                                          # Declare izina variable and assign "MURANGWA Pacifique" to it
+reka *aho_izina_ribitse = &izina;                                                           # Declare a point *aho_izina_ribitse and assign address of izina to it
 
-tangaza_amakuru `Aho izina ribitse kuri mudasobwa: ${aho_izina_ribitse}`;
+tangaza_amakuru `Aho izina ribitse kuri mudasobwa: ${aho_izina_ribitse}`;                   # Log where aho_izina_ribitse (address of izina) to the screent
+tangaza_amakuru `Izina riri muri address ${aho_izina_ribitse} ni ${*aho_izina_ribitse}`     # Log where izina is stored on computer and log it's value

samples/recursion.kin

@@ -4,20 +4,20 @@
 
 
 
-# demonstrating recursion in kin-lang
+# Demonstrating recursion in Kin
 
 
-porogaramu_ntoya factorial(umubare) {
-    niba (umubare == 1 || umubare == 0) {
-        tanga 1;
-    }niba_byanze {
-        tanga umubare * factorial(umubare - 1);
+porogaramu_ntoya factorial(umubare) {               # Declare factorial function
+    niba (umubare == 1 || umubare == 0) {           # Check if a given number is equal to 1 or 0
+        tanga 1;                                    # Return one if the condition above was true
+    }niba_byanze {                                  # If the condition above has failed
+        tanga umubare * factorial(umubare - 1);     # Call factorial again to find the factorial of a given number - 1
     }
 }
 
 
-reka umubare1 = 10;
+reka umubare1 = 10;                                  # Declare variable umubare1 and assign 10 to it.
 
-reka ibisubizo = factorial(umubare1);
+reka ibisubizo = factorial(umubare1);                # Call factorial function to find the factorial of umubare1
 
-tangaza_amakuru `${ibisubizo}`;
+tangaza_amakuru `${ibisubizo}`;                      # Log ibisubizo to the std

samples/relational-logic-operators.kin

@@ -3,26 +3,26 @@
 #   LICENSE file in the root directory of this source tree.
 
 
-# demonstrating relational operators
+# Demonstrating relational operators in Kin
 
 
-reka umubare1 = 10;
-reka umubare2 = 20;
+reka umubare1 = 10;                                                                                                 # Declare variable umubare1 and assign 10 to it
+reka umubare2 = 20;                                                                                                 # Declare variable umubare2 and assign 20 to it
 
-niba ( umubare1 >= 10 && umubare2 <=20 ) {
-    tangaza_amakuru `umubare1 is GREATER THAN OR EQUAL TO 10 AND umubare2 is LESS THAN OR EQUAL TO 20 `;
-} nanone_niba ( umubare1 >= 10 || umubare2 <=20 ) {
-    tangaza_amakuru `umubare1 is GREATER THAN OR EQUAL TO 10 OR umubare2 is LESS THAN OR EQUAL TO 20 `;
-} nanone_niba (umubare1 > 5) {
-    tangaza_amakuru `umubare1 is GREATER THAN 5 `;
-} nanone_niba (umubare2 < 30) {
-    tangaza_amakuru `umubare2 is LESS THAN 20 `;
-} niba_byanze {
-    tangaza_amakuru `ntanakimwe kiricyo mubyatanzwe.`;
+niba ( umubare1 >= 10 && umubare2 <=20 ) {                                                                          # Check if umubare1 >= 10 && umubare2 <=20 is true
+    tangaza_amakuru `umubare1 is GREATER THAN OR EQUAL TO 10 AND umubare2 is LESS THAN OR EQUAL TO 20 `;            # Log info based on the above command
+} nanone_niba ( umubare1 >= 10 || umubare2 <=20 ) {                                                                 # If the first check has failed re-check again if ( umubare1 >= 10 || umubare2 <=20 )
+    tangaza_amakuru `umubare1 is GREATER THAN OR EQUAL TO 10 OR umubare2 is LESS THAN OR EQUAL TO 20 `;             # Log info based on the above command
+} nanone_niba (umubare1 > 5) {                                                                                      # If the both checks above have failed re-check again if (umubare1 > 5)
+    tangaza_amakuru `umubare1 is GREATER THAN 5 `;                                                                  # Log info based on the above command
+} nanone_niba (umubare2 < 30) {                                                                                     # If the above checks have failed re-check again if (umubare2 < 30)
+    tangaza_amakuru `umubare2 is LESS THAN 20 `;                                                                    # Log info based on the above command
+} niba_byanze {                                                                                                     # If all checks above have failed
+    tangaza_amakuru `ntanakimwe kiricyo mubyatanzwe.`;                                                              # Log info based on the above command
 }
 
-this_is_kin = sibyo;
+this_is_kin = sibyo;                                                                                                # Declare a variable called this_is_kin and assign sibyo(true) to it
 
-niba (!this_is_kin) {
-    tangaza_amakuru `this language is NOT kin-lang `;
+niba (!this_is_kin) {                                                                                               # If this_is_kin kin is not true
+    tangaza_amakuru `this language is NOT kin-lang `;                                                               # Log info to the screen
 }

samples/sisitemu.kin

@@ -3,7 +3,9 @@
 #   LICENSE file in the root directory of this source tree.
 
 
-# Running Computer's command directly from kin
+# Running Computer's command directly from Kin
 
-sisitemu `sudo apt update`; # for linux users this will run "sudo apt update" command.
-sisitemu `ipconfig`; # this is for windows users where it will print your ip configurations.
+# sisitemu is built-in function which will run systems commands directly from Kin
+
+sisitemu(`sudo apt update`); # for linux users this will run "sudo apt update" command.          # run sudo apt update directly from Kin
+sisitemu `ipconfig`; # this is for windows users where it will print your ip configurations.     #  run ipconfig directly from Kin

samples/type-casting.kin

@@ -2,12 +2,16 @@
 #   This source code is licensed under the Apache License 2.0 found in the
 #   LICENSE file in the root directory of this source tree.
 
-#type-casting in kin-lang
+# Type Casting in Kin
 
-# type-casting integer -> float (<->)
-# (<->) means vice-versa
+# Casting from integer to float and vice versa 
 
 reka y = 100.12;
 reka z= 10;
-reka umubare = umubare(y); # casting from float to integer
-reka x = umubare_wibice(z); # casting from integer to float
+reka ijambo1 = "10";
+reka umubare1 = umubare(y);             # casting from float to integer
+reka umubare2 = umubare_wibice(z);      # casting from integer to float
+reka ijambo2 = ijambo(z);               # Casting from a number to string
+reka umubare4 = umubare(ijambo1);       # Casting from a string to integer
+
+# umubare, umubare_wibice, ijambo : will be used as built-in functions to perform type casting between strings, numbers and float

samples/unary-operators.kin

@@ -3,7 +3,7 @@
 #   LICENSE file in the root directory of this source tree.
 
 
-# demonstrating unary operators in kin
+# Demonstrating unary operators in kin
 
 reka num1 = 10;
 reka num2 = 2;

samples/user-input.kin

@@ -3,11 +3,11 @@
 #   LICENSE file in the root directory of this source tree.
 
 
-# getting user's input from keyboard - kin-lang
+# Getting user's input from keyboard in Kin
 
-reka num1 = injiza_amakuru `Enter num1:`;
+reka num1 = injiza_amakuru `Enter num1:`;   # Prompt user to input a number
 reka num2 = injiza_amakuru `Enter num2:`;
 reka num3 = injiza_amakuru `Enter num3:`;
-reka average = (num1 + num2 + num3) / 3;
+reka average = (num1 + num2 + num3) / 3;    # Find the average of added numbers
 
-tangaza_amakuru `average is: ${average}`;
+tangaza_amakuru `average is: ${average}`;   # Log the average to the std