Use templates to generate concept exercise introductions (exercism#2364)

sanderploegsma · web-flow · commit bcae59e72543 · 2023-09-20T17:17:48.000+02:00
diff --git a/concepts/chars/introduction.md b/concepts/chars/introduction.md
@@ -4,16 +4,14 @@ The Java `char` type represents the smallest addressable components of text.
 Multiple `char`s can comprise a string such as `"word"` or `char`s can be
 processed independently. Their literals have single quotes e.g. `'A'`.
 
-Java `char`s support Unicode encoding, so in addition to the Latin character set
-most modern writing systems  can be represented,
-e.g.  Greek `'β'`. 
+Java `char`s support Unicode encoding so in addition to the Latin character set
+pretty much all the writing systems in use worldwide can be represented,
+e.g. the Greek letter `'β'`.
 
 There are many builtin library methods to inspect and manipulate `char`s. These
 can be found as static methods of the `java.lang.Character` class.
 
 `char`s are sometimes used in conjunction with a `StringBuilder` object.
 This object has methods that allow a string to be constructed
 character by character and manipulated. At the end of the process
-`toString()` can be called on it to output a complete string.
-
-In order to get chars from the String one could use `String.charAt(index)` method. 
+`toString` can be called on it to output a complete string.
diff --git a/concepts/interfaces/introduction.md b/concepts/interfaces/introduction.md
@@ -10,11 +10,11 @@ public interface Language {
     String speak();
 }
 
-public class ItalianTaveller implements Language, Cloneable {
+public class ItalianTraveller implements Language, Cloneable {
 
     // from Language interface
     public String getLanguageName() {
-        return  "Italiano";
+        return "Italiano";
     }
 
     // from Language interface
@@ -23,8 +23,8 @@ public class ItalianTaveller implements Language, Cloneable {
     }
 
     // from Cloneable interface
-    public Object Clone() {
-        ItalianTaveller it = new ItalianTaveller();
+    public Object clone() {
+        ItalianTraveller it = new ItalianTraveller();
         return it;
     }
 }
diff --git a/concepts/switch-statement/introduction.md b/concepts/switch-statement/introduction.md
@@ -4,12 +4,12 @@ Like an _if/else_ statement, a `switch` statement allows you to change the flow
 
 Some keywords are useful when using a switch statement.
 
-- `switch` : this keyword allows you to declare the structure of the switch. It is followed by the expression or the variable that will make the result change.
-- `case` : you will use this  to declare the differents possibilties for the result.
+- `switch` : this keyword allows you to declare the structure of the switch. It is followed by the expression or the variable that will change the result.
+- `case` : you will use this keyword to declare the different possibilities for the result.
 - `break` : the `break` keyword is very useful in order to stop the execution of the switch at the end of the wanted flow. If you forget it, the program will continue and may lead to unexpected results.
-- `default` : as its name says, use it as a default result when no other case matchs your expression's result.
+- `default` : as its name says, use it as a default result when no other case matches your expression's result.
 
-At their simplest, they test a primitive or string expression and make a decision based on its value. For example:
+At their simplest they test a primitive or string expression and make a decision based on its value. For example:
 
 ```java
 String direction = getDirection();
diff --git a/exercises/concept/annalyns-infiltration/.docs/introduction.md b/exercises/concept/annalyns-infiltration/.docs/introduction.md
@@ -1,5 +1,22 @@
 # Introduction
 
+## Booleans
+
 Booleans in Java are represented by the `boolean` type, which values can be either `true` or `false`.
 
-Java supports three boolean operators: `!` (NOT), `&&` (AND), and `||` (OR).
+Java supports three boolean operators:  
+
+- `!` (NOT): negates the boolean  
+- `&&` (AND): takes two booleans and results in true if they're both true  
+- `||` (OR): results in true if any of the two booleans is true  
+
+**Examples**
+
+```java
+!true // => false
+!false // => true
+true && false // => false
+true && true // => true
+false || false // => false
+false || true // => true
+```
diff --git a/exercises/concept/annalyns-infiltration/.docs/introduction.md.tpl b/exercises/concept/annalyns-infiltration/.docs/introduction.md.tpl
@@ -0,0 +1,3 @@
+# Introduction
+
+%{concept:booleans}
diff --git a/exercises/concept/bird-watcher/.docs/introduction.md b/exercises/concept/bird-watcher/.docs/introduction.md
@@ -1,34 +1,67 @@
-# Arrays
+# Introduction
 
-In Java, data structures that can hold zero or more elements are known as _collections_. An **array** is a collection that has a fixed size/length and whose elements must all be of the same type. Elements can be assigned to an array or retrieved from it using an index. Java arrays are zero-based, meaning that the first element's index is always zero:
+## Arrays
+
+In Java, data structures that can hold zero or more elements are known as _collections_.
+An **array** is a collection that has a fixed size and whose elements must all be of the same type.
+Elements can be assigned to an array or retrieved from it using an index.
+Java arrays use zero-based indexing: the first element's index is 0, the second element's index is 1, etc.
+
+Here is the standard syntax for initializing an array:
+
+```java
+type[] variableName = new type[size];
+```
+
+The `type` is the type of elements in the array which may be a primitive type (e.g. `int`) or a class (e.g. `String`).
+
+The `size` is the number of elements this array will hold (which cannot be changed later).
+After array creation, the elements are initialized to their default values (typically `0`, `false` or `null`).
 
 ```java
 // Declare array with explicit size (size is 2)
 int[] twoInts = new int[2];
+```
+
+Arrays can also be defined using a shortcut notation that allows you to both create the array and set its value:
 
+```java
+// Two equivalent ways to declare and initialize an array (size is 3)
+int[] threeIntsV1 = new int[] { 4, 9, 7 };
+int[] threeIntsV2 = { 4, 9, 7 };
+```
+
+As the compiler can now tell how many elements the array will have, the length can be omitted.
+
+Array elements may be assigned and accessed using a bracketed index notation:
+
+```java
 // Assign second element by index
 twoInts[1] = 8;
 
 // Retrieve the second element by index and assign to the int element
-int element = twoInts[1];
+int secondElement = twoInts[1];
 ```
 
-Arrays can also be defined using a shortcut notation that allows you to both create the array and set its value. As the compiler can now tell how many elements the array will have, the length can be omitted:
+Accessing an index that is outside of the valid indexes for the array results in an `IndexOutOfBoundsException`.
+
+Arrays can be manipulated by either calling an array instance's methods or properties, or by using the static methods defined in the `Arrays` class (typically only used in generic code).
+The most commonly used property for arrays is its length which can be accessed like this:
 
 ```java
-// Two equivalent ways to declare and initialize an array (size is 3)
-int[] threeIntsV1 = new int[] { 4, 9, 7 };
-int[] threeIntsV2 = { 4, 9, 7 };
+int arrayLength = someArray.length;
 ```
 
-Arrays can be manipulated by either calling an array instance's methods or properties, or by using the static methods defined in the `Arrays` class.
+Java also provides a helpful utility class [`java.util.Arrays`](https://docs.oracle.com/en/java/javase/11/docs/api/java.base/java/util/Arrays.html) that has lots of useful array-related methods (eg. `Arrays.equals`).
+
+Java also supports [multi-dimensional arrays](https://www.programiz.com/java-programming/multidimensional-array) like `int[][] arr = new int[3][4];` which can be very useful.
 
-The fact that an array is also a _collection_ means that, besides accessing values by index, you can iterate over _all_ its values using a `foreach` loop:
+The fact that an array is also a _collection_ means that, besides accessing values by index, you can iterate over _all_ its values using a `for-each` loop:
 
 ```java
 char[] vowels = { 'a', 'e', 'i', 'o', 'u' };
 
-for(char vowel:vowels) {
+for(char vowel: vowels) {
     // Output the vowel
     System.out.print(vowel);
 }
diff --git a/exercises/concept/bird-watcher/.docs/introduction.md.tpl b/exercises/concept/bird-watcher/.docs/introduction.md.tpl
@@ -0,0 +1,3 @@
+# Introduction
+
+%{concept:arrays}
diff --git a/exercises/concept/blackjack/.docs/introduction.md b/exercises/concept/blackjack/.docs/introduction.md
@@ -1,10 +1,12 @@
 # Introduction
 
-## Logical Operators
+## Conditionals If
+
+### Logical Operators
 
 Java supports the three logical operators `&&` (AND), `||` (OR), and `!` (NOT).
 
-## If statement
+### If statement
 
 The underlying type of any conditional operation is the `boolean` type, which can have the value of `true` or `false`. Conditionals are often used as flow control mechanisms to check for various conditions. For checking a particular case an `if` statement can be used, which executes its code if the underlying condition is `true` like this:
 
@@ -28,7 +30,7 @@ if(val == 10) {
 }
 ```
 
-## Switch statement
+### Switch statement
 
 Java also provides a `switch` statement for scenarios with multiple options.
 
diff --git a/exercises/concept/blackjack/.docs/introduction.md.tpl b/exercises/concept/blackjack/.docs/introduction.md.tpl
@@ -0,0 +1,3 @@
+# Introduction
+
+%{concept:conditionals-if}
diff --git a/exercises/concept/cars-assemble/.docs/introduction.md b/exercises/concept/cars-assemble/.docs/introduction.md
@@ -1,13 +1,15 @@
 # Introduction
 
+## Numbers
+
 There are two different types of numbers in Java:
 
 - Integers: numbers with no digits behind the decimal separator (whole numbers). Examples are `-6`, `0`, `1`, `25`, `976` and `-500000`.
 - Floating-point numbers: numbers with zero or more digits behind the decimal separator. Examples are `-20.4`, `0.1`, `2.72`, `16.984025` and `1024.0`.
 
 The two most common numeric types in Java are `int` and `double`. An `int` is a 32-bit integer and a `double` is a 64-bit floating-point number.
 
-Arithmetic is done using the standard arithmetic operators. Numbers can be compared using the standard numeric comparison operators and the equality (`==`) and inequality (`!=`) operators.
+Arithmetic is done using the standard arithmetic operators. Numbers can be compared using the standard numeric comparison operators (eg. `5 > 4` and `4 <= 5`) and the equality (`==`) and inequality (`!=`) operators.
 
 Java has two types of numeric conversions:
 
@@ -30,4 +32,4 @@ if (x == 5) {
 }
 ```
 
-The condition of an `if` statement must be of type `boolean`. Java has no concept of _truthy_ values.
+The condition of an `if` statement must be of type `boolean`.
diff --git a/exercises/concept/cars-assemble/.docs/introduction.md.tpl b/exercises/concept/cars-assemble/.docs/introduction.md.tpl
@@ -0,0 +1,3 @@
+# Introduction
+
+%{concept:numbers}
diff --git a/exercises/concept/elons-toy-car/.docs/introduction.md b/exercises/concept/elons-toy-car/.docs/introduction.md
@@ -1,5 +1,7 @@
 # Introduction
 
+## Classes
+
 The primary object-oriented construct in Java is the _class_, which is a combination of data (_fields_) and behavior (_methods_). The fields and methods of a class are known as its _members_.
 
 Access to members can be controlled through access modifiers, the two most common ones being:
@@ -55,7 +57,7 @@ Private fields are usually updated as a side effect of calling a method. Such me
 class CarImporter {
     private int carsImported;
 
-    public void ImportCars(int numberOfCars)
+    public void importCars(int numberOfCars)
     {
         // Update private field from public method
         carsImported = carsImported + numberOfCars;
diff --git a/exercises/concept/elons-toy-car/.docs/introduction.md.tpl b/exercises/concept/elons-toy-car/.docs/introduction.md.tpl
@@ -0,0 +1,3 @@
+# Introduction
+
+%{concept:classes}
diff --git a/exercises/concept/football-match-reports/.docs/introduction.md b/exercises/concept/football-match-reports/.docs/introduction.md
@@ -1,5 +1,7 @@
 # Introduction
 
+## Switch Statements
+
 Like an _if/else_ statement, a `switch` statement allows you to change the flow of the program by conditionally executing code. The difference is that a `switch` statement can only compare the value of a primitive or string expression against pre-defined constant values.
 
 Some keywords are useful when using a switch statement.
diff --git a/exercises/concept/football-match-reports/.docs/introduction.md.tpl b/exercises/concept/football-match-reports/.docs/introduction.md.tpl
@@ -0,0 +1,3 @@
+# Introduction
+
+%{concept:switch-statement}
diff --git a/exercises/concept/karls-languages/.docs/introduction.md.tpl b/exercises/concept/karls-languages/.docs/introduction.md.tpl
@@ -0,0 +1,5 @@
+# Introduction
+
+%{concept:generic-types}
+
+%{concept:lists}
diff --git a/exercises/concept/lasagna/.docs/introduction.md b/exercises/concept/lasagna/.docs/introduction.md
@@ -1,18 +1,20 @@
 # Introduction
 
-Java is a statically-typed language, which means that everything has a type at compile-time. Assigning a value to a name is referred to as defining a variable. A variable is defined by explicitly specifying its type.
+## Basics
+
+Java is a statically-typed language, which means that the type of a variable is known at compile-time. Assigning a value to a name is referred to as defining a variable. A variable is defined by explicitly specifying its type.
 
 ```java
 int explicitVar = 10;
 ```
 
-Updating a variable's value is done through the `=` operator. Once defined, a variable's type can never change.
+Updating a variable's value is done through the `=` operator. Here, `=` does not represent mathematical equality. It simply assigns a value to a variable. Once defined, a variable's type can never change.
 
 ```java
 int count = 1; // Assign initial value
 count = 2;     // Update to new value
 
-// Compiler error when assigning different type
+// Compiler error when assigning a different type
 // count = false;
 ```
 
@@ -24,7 +26,7 @@ class Calculator {
 }
 ```
 
-A function within a class is referred to as a _method_. Each method can have zero or more parameters. All parameters must be explicitly typed, there is no type inference for parameters. Similarly, the return type must also be made explicit. Values are returned from functions using the `return` keyword. To allow a method to be called by other classes, the `public` access modifier must be added.
+A function within a class is referred to as a _method_. Each method can have zero or more parameters. All parameters must be explicitly typed, there is no type inference for parameters. Similarly, the return type must also be made explicit. Values are returned from methods using the `return` keyword. To allow a method to be called by other classes, the `public` access modifier must be added.
 
 ```java
 class Calculator {
@@ -34,10 +36,10 @@ class Calculator {
 }
 ```
 
-Invoking a method is done by specifying its class and method name and passing arguments for each of the method's parameters.
+Invoking/calling a method is done by specifying its class and method name and passing arguments for each of the method's parameters.
 
 ```java
-int sum = new Calculator().add(1, 2);
+int sum = new Calculator().add(1, 2);  // here the  "add" method has been called to perform the task of addition 
 ```
 
 Scope in Java is defined between the `{` and `}` characters.
diff --git a/exercises/concept/lasagna/.docs/introduction.md.tpl b/exercises/concept/lasagna/.docs/introduction.md.tpl
@@ -0,0 +1,3 @@
+# Introduction
+
+%{concept:basics}
diff --git a/exercises/concept/log-levels/.docs/introduction.md b/exercises/concept/log-levels/.docs/introduction.md
@@ -1,5 +1,7 @@
 # Introduction
 
+## Strings
+
 A `String` in Java is an object that represents immutable text as a sequence of Unicode characters (letters, digits, punctuation, etc.). Double quotes are used to define a `String` instance:
 
 ```java
diff --git a/exercises/concept/log-levels/.docs/introduction.md.tpl b/exercises/concept/log-levels/.docs/introduction.md.tpl
@@ -0,0 +1,3 @@
+# Introduction
+
+%{concept:strings}
diff --git a/exercises/concept/need-for-speed/.docs/introduction.md b/exercises/concept/need-for-speed/.docs/introduction.md
@@ -1,5 +1,7 @@
 # Introduction
 
+## Constructors
+
 Creating an instance of a _class_ is done by calling its _constructor_ through the `new` operator. A constructor is a special type of method whose goal is to initialize a newly created instance. Constructors look like regular methods, but without a return type and with a name that matches the class's name.
 
 ```java
diff --git a/exercises/concept/need-for-speed/.docs/introduction.md.tpl b/exercises/concept/need-for-speed/.docs/introduction.md.tpl
@@ -0,0 +1,3 @@
+# Introduction
+
+%{concept:constructors}
diff --git a/exercises/concept/remote-control-competition/.docs/introduction.md b/exercises/concept/remote-control-competition/.docs/introduction.md
@@ -1,5 +1,7 @@
 # Introduction
 
+## Interfaces
+
 An interface is a type containing members defining a group of related functionality. It distances the uses of a class from the implementation allowing multiple different implementations or support for some generic behavior such as formatting, comparison or conversion.
 
 The syntax of an interface is similar to that of a class except that methods appear as the signature only and no body is provided.
@@ -24,7 +26,7 @@ public class ItalianTraveller implements Language, Cloneable {
 
     // from Cloneable interface
     public Object clone() {
-        ItalianTaveller it = new ItalianTaveller();
+        ItalianTraveller it = new ItalianTraveller();
         return it;
     }
 }
diff --git a/exercises/concept/remote-control-competition/.docs/introduction.md.tpl b/exercises/concept/remote-control-competition/.docs/introduction.md.tpl
@@ -0,0 +1,3 @@
+# Introduction
+
+%{concept:interfaces}
diff --git a/exercises/concept/salary-calculator/.docs/introduction.md b/exercises/concept/salary-calculator/.docs/introduction.md
@@ -1,5 +1,7 @@
 # Introduction
 
+## Ternary Operators
+
 The _ternary operator_ is a lightweight, compact alternative for simple _if/else_ statements. Usually used in (but not restricted to) return statements, it needs just one single line to make the decision, returning the left value if the expression is `true` and the right value if `false`, as follows:
 
 ```java
diff --git a/exercises/concept/salary-calculator/.docs/introduction.md.tpl b/exercises/concept/salary-calculator/.docs/introduction.md.tpl
@@ -0,0 +1,3 @@
+# Introduction
+
+%{concept:ternary-operators}
diff --git a/exercises/concept/squeaky-clean/.docs/introduction.md b/exercises/concept/squeaky-clean/.docs/introduction.md
@@ -1,5 +1,7 @@
 # Introduction
 
+## Chars
+
 The Java `char` type represents the smallest addressable components of text.
 Multiple `char`s can comprise a string such as `"word"` or `char`s can be
 processed independently. Their literals have single quotes e.g. `'A'`.
diff --git a/exercises/concept/squeaky-clean/.docs/introduction.md.tpl b/exercises/concept/squeaky-clean/.docs/introduction.md.tpl
@@ -0,0 +1,3 @@
+# Introduction
+
+%{concept:chars}
diff --git a/exercises/concept/wizards-and-warriors/.docs/introduction.md b/exercises/concept/wizards-and-warriors/.docs/introduction.md
@@ -1,5 +1,7 @@
 # Introduction
 
+## Inheritance
+
 Inheritance is a core concept in OOP (Object Oriented Programming). It donates IS-A relationship.
 It literally means in programming as it means in english, inheriting features from parent(in programming features is normally functions
 and variables).
diff --git a/exercises/concept/wizards-and-warriors/.docs/introduction.md.tpl b/exercises/concept/wizards-and-warriors/.docs/introduction.md.tpl
@@ -0,0 +1,3 @@
+# Introduction
+
+%{concept:inheritance}

Original file line number	Diff line number	Diff line change
`@@ -10,11 +10,11 @@ public interface Language {`
`10`	`10`	`String speak();`
`11`	`11`	`}`
`12`	`12`
`13`		`-public class ItalianTaveller implements Language, Cloneable {`
	`13`	`+public class ItalianTraveller implements Language, Cloneable {`
`14`	`14`
`15`	`15`	`// from Language interface`
`16`	`16`	`public String getLanguageName() {`
`17`		`- return "Italiano";`
	`17`	`+ return "Italiano";`
`18`	`18`	`}`
`19`	`19`
`20`	`20`	`// from Language interface`
`@@ -23,8 +23,8 @@ public class ItalianTaveller implements Language, Cloneable {`
`23`	`23`	`}`
`24`	`24`
`25`	`25`	`// from Cloneable interface`
`26`		`- public Object Clone() {`
`27`		`- ItalianTaveller it = new ItalianTaveller();`
	`26`	`+ public Object clone() {`
	`27`	`+ ItalianTraveller it = new ItalianTraveller();`
`28`	`28`	`return it;`
`29`	`29`	`}`
`30`	`30`	`}`
Original file line number	Diff line number	Diff line change
`@@ -0,0 +1,3 @@`
	`1`	`+# Introduction`
	`2`	`+`
	`3`	`+%{concept:booleans}`
Original file line number	Diff line number	Diff line change
`@@ -0,0 +1,3 @@`
	`1`	`+# Introduction`
	`2`	`+`
	`3`	`+%{concept:arrays}`
Original file line number	Diff line number	Diff line change
`@@ -0,0 +1,3 @@`
	`1`	`+# Introduction`
	`2`	`+`
	`3`	`+%{concept:conditionals-if}`