improve wordings

Author: forax

chapter01-basic_types.jsh

@@ -42,7 +42,7 @@ var result = value + value;
 
 // ### primitive conversions
 // You have automatic conversions if there is no loose of precision
-// unless it's to convert to double or float which you are always allowed.
+// and converting to double or float is always allowed
 int intValue = 13;
 long longValue = intValue;
 

chapter04-numbers.jsh

@@ -89,7 +89,7 @@ System.out.println(0.0 / 0.0);
 System.out.println(Double.NaN);
 
 // ### NaN
-// Not a Number is very weird, because by definition, it's the number which is not equals to itself
+// Not a Number is very weird, because by definition, it's the number which is not equal to itself
 
 // Don't use == to test NaN, it will not work
 System.out.println(Double.NaN == Double.NaN);
@@ -100,7 +100,7 @@ boolean isNotANumber(double x) {
 }
 System.out.println(isNotANumber(Double.NaN));
 
-// The method isNotANumber already exist in Double, `Double.isNaN()`
+// An equivalent static method to isNotANumber already exist in Double, `Double.isNaN()`
 System.out.println(Double.isNaN(Double.NaN));
 
 

chapter05-control_flow.jsh

@@ -24,6 +24,8 @@ System.out.println(x);
 // ## If
 
 // ### Test with `if`
+// the construct `if` execute the block of code that follow if the condition in between
+// the parenthesis is true
 void oldEnough(int age) {
   if (age >= 21) {
     System.out.println("you are old enough to drink a beer");
@@ -32,6 +34,8 @@ void oldEnough(int age) {
 oldEnough(22);
 
 // ### Test with `if ... else`
+// you can append the construct `else` after an `if` to execute a block of code
+// if the condition is not true
 void oldEnough(int age) {
   if (age >= 21) {
     System.out.println("you are old enough to drink a beer");
@@ -141,6 +145,7 @@ printKind(new Car(4));
 // ## Loops
 
 // ### `while` loop
+// a `while` loop execute the block of code while the condition in between parenthesis is true
 void printFirstIntegers(int n) {
   var i = 0;
   while(i < n) {
@@ -151,14 +156,20 @@ void printFirstIntegers(int n) {
 printFirstIntegers(5);
 
 // ### `for` loop
+// a for loop is a convenient way to write a `while` loop in case you do a while on a variable,
+// so instead of using the `while` loop above, one can write this for loop
 void printFirstIntegers(int n) {
   for(var i = 0; i < n; i++) {
     System.out.println(i);
   }
 }
 printFirstIntegers(5);
 
+
+
 // ### `for` loop on array or list
+// Java as a special loop for iterating over the content of an array or a list,
+// it using the keyword `for`, but the declared variable contains each element one by one
 var list = List.of("iron man", "captain america", "black panther");
 for(var value: list) {
   System.out.println(value);

chapter07-interface.jsh

@@ -5,7 +5,7 @@
 // # Interface
 // Java is a typed language, even if you don't explicitly write a type
 // the compiler you compute the type of every variables
-// Once you start to want to mix several records, you need to declare
+// Once you start to want to mix several records, you may need to declare
 // common type between records, such type are known as interface
 
 // ## The problem
@@ -31,7 +31,7 @@ for(var figure: figures) {
 
 // The problem is that compiler try to find the type of the element of the list
 // and find that they are java.lang.Object, and Object has no method area()
-// so it doens't compile
+// so the code does not compile
 
 
 // ### Interface and abstract method
@@ -68,7 +68,7 @@ for(var figure: figures) {
 
 // An interface is a common type that you need to declare when you want to
 // call the same method on different records
-// At runtime, when you call a method of the interface, the interpreter calls
+// At runtime, when you call a method of the interface, the virtual machine calls
 // the correct implementation (this is called polymorphism)
 
 
@@ -100,14 +100,14 @@ System.out.println(new Rectangle(3, 4).isBig());
 
 // Because a default method is declared on the interface, all records that
 // implement that interface will have that method. Default methods are named like this
-// because if the record doesn't define the method itself, the method will be provided
-// by default. 
+// because if a record that implements the interface doesn't define the method,
+// the method will be provided by default.
 
 
 // ## Functional interface
 // An interface with only one abstract method is equivalent to a function type.
 // We name this kind of interfaces, _functional_ interfaces.
-// They can be implemented by supplementary constructs.
+// They can be implemented by two special constructs.
 
 // ### Lambda
 // The parameter are declared in between the parenthesis and the body of the method

chapter09-list_and_map.jsh

@@ -74,14 +74,14 @@ countries.forEach(country -> System.out.println(country));
 var unmodifiableList = List.copyOf(modifiableCountries);
 System.out.println(unmodifiableList);
 
-// To create a modifiable list from an unmodifiable one using ArrayList(List)
+// To create a modifiable list from an unmodifiable one using `new ArrayList(List)`
 // In that case you don't have to specify the type of the elements
 // the compiler already knows the type of list hence the <> (diamond)
 var modifiableList = new ArrayList<>(unmodifiableList);
 System.out.println(modifiableList);
 
 // ### Useful patterns
-// To remove some elements depending on a predicate
+// To remove some elements depending on a predicate (if something is true)
 var elements = new ArrayList<>(List.of("table", "chair", "stool"));
 elements.removeIf(element -> element.charAt(0) == 'c');
 System.out.println(elements);
@@ -171,12 +171,13 @@ persons.forEach(person -> group.computeIfAbsent(person.name(), name -> new Array
                                 .add(person));
 System.out.println(group);
 
-// to count the number of occurrence, use `merge()`
+// to count the number of occurrence, use `merge()` that takes a key, a value and the function
+// to call if there is already an existing value to combine them
 var letters = List.of("a", "b", "e", "b");
 var occurenceMap = new HashMap<String, Integer>();
 letters.forEach(letter -> occurenceMap.merge(letter, 1, Integer::sum));
 System.out.println(occurenceMap);
 
 
 // ### More on transformations
-// To do more transformations of lists and maps, the Stream API is richer
+// To do more transformations of lists and maps, use the Stream API.

chapter10-string_formatting.jsh

@@ -48,7 +48,7 @@ String concatenate(List<?> list) {
   var string = "";
   var separator = "";
   for(var item: list) {
-    string = string + separator + item;
+    string = string + separator + item;  // creates two many strings, ahhhh
     separator = ", ";
   } 
   return string;
@@ -71,7 +71,8 @@ String concatenate(List<?> list) {
 System.out.println(concatenate(strings));
 System.out.println(concatenate(friends));
 
-// > Don't use '+' inside a `append()`, you already have a StringBuilder, so use append() instead
+// > Don't use '+' inside a call to  `append()`, you already have a StringBuilder,
+// so use append() instead
 
 
 // ### Concatenation with String.join()

chapter17-enum.jsh

@@ -136,7 +136,7 @@ enum FileListMode {
   DIRECTORY(path -> NORMAL.test(path) && Files.isDirectory(path))
   ;
   private final FilePredicate predicate;
-  private FileListMode(FilePredicate predicate) {
+  FileListMode(FilePredicate predicate) {
     this.predicate = predicate;
   }
   public boolean test(Path path) throws IOException {

chapter18-nested_classes.jsh

@@ -173,7 +173,7 @@ Object box = new Object() {
 };
 System.out.println(box.sum);  // doesn't compile
 
-// If we are using var, it works !
+// using `var`, it works !
 var box = new Object() {
   int sum;
 };

chapter23-limitation_of_generics.jsh

@@ -7,16 +7,39 @@
 
 // ## No reification
 
-In Java, generics are purely a compiler construct, the type arguments of a generics
-are not available at runtime. 
+// In Java, generics are purely a compiler construct, the type arguments of a generics
+// are not available at runtime. 
+// - for a type variable (`T`, `E`, etc), the actual value at the execution, the type argument is not present at runtime. 
+// - for a parameterized type (`List>String<`) the type argument (`String` here) is not available too
 
-For a type variable (`T`, `E`, etc), the actual value at the execution, the type argument
-is not present at runtime. For a parameterized type (`List>String<`
+// ### No type argument
 
-- instanceof 
-- cast
-- 
-- array creation
+// Which means that all operations that requires the type argument at runtime doesn't work.
+// So the compiler doesn't allow you to write
+// - `new T(...)` 
+// - `new T[5]`
+// - `instanceof T` and `instanceof Foo<String>`
+// - `catch(T ..)` and `catch(Foo<String>)`, moreover 
+
+// ### Unchecked Warnings
+
+// You can still write a cast like `(T)` or `(Foo<String>)`,
+// but the complier will warn you that this is not a safe cast.
+
+// An example of cast that works
+List<Object> objectList = List.of("foo", "bar");
+List<String> stringList = (List<String>) (List<?>) objectList; // warning, this is dangerous
+                                                               // but it works in practice
+
+// An example of cast that doesn't work
+List<String> stringList = new ArrayList<>();
+stringList.add("foo");
+List<Object> objectList = (List<Object>) (List<?>) stringList; // dangerous, don't work !
+objectList.add(4321);
+System.out.println(stringList.get(1));               // fail at runtime
+
+// Hopefully, those casts are rare in practice because casts in general are rare
+// mostly because if you have a cast it means that you have lost the type at some point.
 
 
 // ## Array of parameterized type
@@ -46,7 +69,6 @@ objectArray[0] = 3;   // ArrayStoreException
 // the array. Anyway, it's unsafe.
 
 
-
 // ### varargs
 
 

chapter30-data_structure.jsh

@@ -5,72 +5,6 @@
 // In Java, there are already plenty of data structures already available
 // there are grouped under the name the collection API.
 
-// to create a simple list
-var list = List.of(1, 2, 3);
-
-// a list is an indexed data structure that stores object in the order of insertions
-// get() access to an element given an index
-var firstElement = list.get(0);
-var lastElement = list.get(list.size() - 1);
-
-// contains return true if a value is contained in the list
-System.out.println(list.contains(4));
-
-// indexOf returns the first index of the element in the list
-System.out.println(list.indexOf(2));
-
-// to loop over the elements of a list, we have a special syntax using the keyword 'for'
-var countries = List.of('UK', 'US', 'France');
-for(var country: countries) {
-  System.out.println(country);
-}
-
-// you can also loop over the elements using a method forEach
-// if you don't understand this one, don't panic, we will see it later
-countries.forEach(country -> System.out.println(country));
-
-
-// a list also defines the method equals() and toString(), so
-// you can print a list or test if two list are equals
-System.out.println(countries);
-System.out.println(list.equals(countries));
-
-
-// in Java, depending on how you create a collection it can be changed
-// after creation or not. Implementation that allow mutation after creation
-// are called modifiable
-
-// by example, the list above (created with the static method of()) is not modifiable
-//countries.set(0, 'Poland')  // throws an UnsupportedOperationException
-
-// To create a modifiable list, we use an ArrayList, created using the operator 'new'
-// here because there is no element in the list, the compiler has no way to know
-// the type of the elements so we have to provide it in between angle brackets ('<' and '>')
-var modifiableCountries = new ArrayList<String>();
-
-// To add elements in a list, we have the method add()
-modifiableCountries.add("UK");
-modifiableCountries.add("US");
-modifiableCountries.add("France");
-modifiableCountries.add("Poland");
-
-// to remove an element, we have the method remove()
-modifiableCountries.remove("UK");
-
-// an unmodifiable list or a modifiable list have the same set of methods,
-// so you can loop over the modiable list the same way
-for(var country: modifiableCountries) {
-  System.out.println(country);
-}
-
-// You can create a modifiable list from an unmodifiable one using new ArrayList
-// with the unmodifiable list as argument
-// In that case you don't have to specify the type of the elements
-// the compiler already knows the type of list hence the <> (diamond)
-var modifiableList = new ArrayList<>(list);
-System.out.println(modifiableList);
-
-
 // Lists are not the only data structure in Java, you also have set, queue and map
 // - a set is set where you can not store the same object twice
 //   (object are the same is equals() return true)
@@ -82,8 +16,8 @@ System.out.println(modifiableList);
 var authors = Set.of("J.R.R. Tolkien", "Philip K. Dick", "George R.R. Martin");
 System.out.println(authors);
 
-// elements inside a set are organized in a way that make contains fast
-System.out.println(authors.contains(""Philip K. Dick""));
+// elements inside a set are organized in a way that make `contains` fast
+System.out.println(authors.contains("Philip K. Dick"));
 
 // there are 3 modifiable sets
 // - HashSet

guide/chapter01-basic_types.md

@@ -52,7 +52,7 @@ var result = value + value;
 
 ### primitive conversions
 You have automatic conversions if there is no loose of precision
-unless it's to convert to double or float which you are always allowed.
+and converting to double or float is always allowed
 ```java
 int intValue = 13;
 long longValue = intValue;

guide/chapter04-numbers.md

@@ -113,7 +113,7 @@ System.out.println(Double.NaN);
 ```
 
 ### NaN
-Not a Number is very weird, because by definition, it's the number which is not equals to itself
+Not a Number is very weird, because by definition, it's the number which is not equal to itself
 
 Don't use == to test NaN, it will not work
 ```java
@@ -128,7 +128,7 @@ boolean isNotANumber(double x) {
 System.out.println(isNotANumber(Double.NaN));
 ```
 
-The method isNotANumber already exist in Double, `Double.isNaN()`
+An equivalent static method to isNotANumber already exist in Double, `Double.isNaN()`
 ```java
 System.out.println(Double.isNaN(Double.NaN));
 ```