Format concept docs (#2591)

concepts/basics/about.md

@@ -1,12 +1,14 @@
 # About
 
-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.
+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.
 
 ```java
 int explicitVar = 10; // Explicitly typed
 ```
 
-The value of a variable can be assigned and updated using the [`=` operator][assignment]. Once defined, a variable's type can never change.
+The value of a variable can be assigned and updated using the [`=` operator][assignment].
+Once defined, a variable's type can never change.
 
 ```java
 int count = 1; // Assign initial value
@@ -16,7 +18,13 @@ count = 2;     // Update to new value
 // count = false;
 ```
 
-Java is an object-oriented language and requires all functions to be defined in a _class_, which are defined using the [`class` keyword][classes]. A function within a class is referred to as a _method_. Each [method][methods] 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][return]. To allow a method to be called by other classes, the `public` access modifier must be added.
+Java is an object-oriented language and requires all functions to be defined in a _class_, which are defined using the [`class` keyword][classes].
+A function within a class is referred to as a _method_.
+Each [method][methods] 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][return].
+To allow a method to be called by other classes, the `public` access modifier must be added.
 
 ```java
 class Calculator {
@@ -32,7 +40,8 @@ Invoking a method is done by specifying its class and method name and passing ar
 int sum = new Calculator().add(1, 2);
 ```
 
-If a method does not use any class _state_ (which is the case in this exercise), the method can be made _static_ using the `static` modifier. Similarly, if a class only has static methods, it too can be made static using the `static` modifier.
+If a method does not use any class _state_ (which is the case in this exercise), the method can be made _static_ using the `static` modifier.
+Similarly, if a class only has static methods, it too can be made static using the `static` modifier.
 
 ```java
 static class Calculator {
@@ -44,7 +53,8 @@ static class Calculator {
 
 Scope in Java is defined between the `{` and `}` characters.
 
-Java supports two types of [comments][comments]. Single line comments are preceded by `//` and multiline comments are inserted between `/*` and `*/`.
+Java supports two types of [comments][comments].
+Single line comments are preceded by `//` and multiline comments are inserted between `/*` and `*/`.
 
 Integer values are defined as one or more (consecutive) digits and support the [default mathematical operators][operators].
 

concepts/basics/introduction.md

@@ -1,12 +1,17 @@
 # Introduction
 
-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 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. Here, `=` does not represent mathematical equality. It simply assigns a value to a variable. 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
@@ -16,15 +21,21 @@ count = 2;     // Update to new value
 // count = false;
 ```
 
-Java is an [object-oriented language][object-oriented-programming] and requires all functions to be defined in a _class_. The `class` keyword is used to define a class.
+Java is an [object-oriented language][object-oriented-programming] and requires all functions to be defined in a _class_.
+The `class` keyword is used to define a class.
 
 ```java
 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 methods 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 {
@@ -37,11 +48,12 @@ class Calculator {
 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);  // here the  "add" method has been called to perform the task of addition 
+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.
 
-Java supports two types of comments. Single line comments are preceded by `//` and multiline comments are inserted between `/*` and `*/`.
+Java supports two types of comments.
+Single line comments are preceded by `//` and multiline comments are inserted between `/*` and `*/`.
 
 [object-oriented-programming]: https://docs.oracle.com/javase/tutorial/java/javaOO/index.html

concepts/booleans/about.md

@@ -4,13 +4,14 @@ Booleans in Java are represented by the `boolean` type, which values can be eith
 
 Java supports three [boolean operators][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  
+- `!` (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
 
 The `&&` and `||` operators use _short-circuit evaluation_, which means that the right-hand side of the operator is only evaluated when needed.
 
-These are also known as conditional or logical operators. `!` is sometimes classified as a bitwise operation in the documentation but it has the conventional _NOT_ semantics.
+These are also known as conditional or logical operators.
+`!` is sometimes classified as a bitwise operation in the documentation but it has the conventional _NOT_ semantics.
 
 ```java
 true || false // => true
@@ -22,7 +23,9 @@ true && true // => true
 !false // => true
 ```
 
-The three boolean operators each have a different [_operator precedence_][precedence]. As a consequence, they are evaluated in this order: `not` first, `&&` second, and finally `||`. If you want to 'escape' these rules, you can enclose a boolean expression in parentheses (`()`), as the parentheses have an even higher operator precedence.
+The three boolean operators each have a different [_operator precedence_][precedence].
+As a consequence, they are evaluated in this order: `not` first, `&&` second, and finally `||`.
+If you want to 'escape' these rules, you can enclose a boolean expression in parentheses (`()`), as the parentheses have an even higher operator precedence.
 
 ```java
 !true && false   // => false

concepts/chars/about.md

@@ -1,7 +1,6 @@
 # About
 
-`char`s are generally easy to use. They can be extracted from strings, added back
-(by means of a string builder), defined and initialised using literals with single quotes, as in `char ch = 'A';`
-, assigned and compared.
+`char`s are generally easy to use.
+They can be extracted from strings, added back (by means of a string builder), defined and initialised using literals with single quotes, as in `char ch = 'A';`, assigned and compared.
 
 The Character class encapsulates the char value.

concepts/chars/introduction.md

@@ -1,17 +1,14 @@
 # Introduction
 
 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'`.
+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
-pretty much all the writing systems in use worldwide can be represented,
-e.g. the Greek letter `'β'`.
+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.
+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.
+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.

concepts/classes/about.md

@@ -1,17 +1,20 @@
 # About
 
-The primary object-oriented construct in Java is the _class_, which is a combination of data ([_fields_][fields]), also known as instance variables, and behavior ([_methods_][methods]). The fields and methods of a class are known as its _members_.
+The primary object-oriented construct in Java is the _class_, which is a combination of data ([_fields_][fields]), also known as instance variables, and behavior ([_methods_][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:
 
 - [`public`][public]: the member can be accessed by any code (no restrictions).
 - [`private`][private]: the member can only be accessed by code in the same class.
 
-In Java if no access modifier is specified, the default is _package visibility_. In this case, the member is visible to all classes defined into the same package.
+In Java if no access modifier is specified, the default is _package visibility_.
+In this case, the member is visible to all classes defined into the same package.
 
 The above-mentioned grouping of related data and behavior plus restricting access to members is known as [_encapsulation_][encapsulation], which is one of the core object-oriented concepts.
 
-You can think of a class as a template for creating instances of that class. To [create an instance of a class][creating-objects] (also known as an _object_), the [`new` keyword][new] is used:
+You can think of a class as a template for creating instances of that class.
+To [create an instance of a class][creating-objects] (also known as an _object_), the [`new` keyword][new] is used:
 
 ```java
 class Car {
@@ -34,7 +37,9 @@ class Car {
 }
 ```
 
-One can optionally assign an initial value to a field. If a field does _not_ specify an initial value, it will be set to its type's [default value][default-values]. An instance's field values can be accessed and updated using dot-notation.
+One can optionally assign an initial value to a field.
+If a field does _not_ specify an initial value, it will be set to its type's [default value][default-values].
+An instance's field values can be accessed and updated using dot-notation.
 
 ```java
 class Car {
@@ -53,7 +58,8 @@ newCar.year;   // => 0
 newCar.year = 2018;
 ```
 
-Private fields are usually updated as a side effect of calling a method. Such methods usually don't return any value, in which case the return type should be [`void`][void]:
+Private fields are usually updated as a side effect of calling a method.
+Such methods usually don't return any value, in which case the return type should be [`void`][void]:
 
 ```java
 class CarImporter {
@@ -67,9 +73,11 @@ class CarImporter {
 }
 ```
 
-Note that is not customary to use public fields in Java classes. Private fields are typically used which are accessed through [_getters_ and _setters_][so-getters-setters].
+Note that is not customary to use public fields in Java classes.
+Private fields are typically used which are accessed through [_getters_ and _setters_][so-getters-setters].
 
-Within a class, the [`this` keyword][this] will refer to the current class. This is especially useful if a parameter has the same name as a field:
+Within a class, the [`this` keyword][this] will refer to the current class.
+This is especially useful if a parameter has the same name as a field:
 
 ```java
 class CarImporter {

concepts/classes/introduction.md

@@ -1,13 +1,15 @@
 # Introduction
 
-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_.
+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:
 
 - `public`: the member can be accessed by any code (no restrictions).
 - `private`: the member can only be accessed by code in the same class.
 
-You can think of a class as a template for creating instances of that class. To create an instance of a class (also known as an _object_), the `new` keyword is used:
+You can think of a class as a template for creating instances of that class.
+To create an instance of a class (also known as an _object_), the `new` keyword is used:
 
 ```java
 class Car {
@@ -30,7 +32,9 @@ class Car {
 }
 ```
 
-One can optionally assign an initial value to a field. If a field does _not_ specify an initial value, it wll be set to its type's default value. An instance's field values can be accessed and updated using dot-notation.
+One can optionally assign an initial value to a field.
+If a field does _not_ specify an initial value, it wll be set to its type's default value.
+An instance's field values can be accessed and updated using dot-notation.
 
 ```java
 class Car {
@@ -49,7 +53,8 @@ newCar.year;   // => 0
 newCar.year = 2018;
 ```
 
-Private fields are usually updated as a side effect of calling a method. Such methods usually don't return any value, in which case the return type should be `void`:
+Private fields are usually updated as a side effect of calling a method.
+Such methods usually don't return any value, in which case the return type should be `void`:
 
 ```java
 class CarImporter {

concepts/constructors/about.md

@@ -1,6 +1,8 @@
 # About
 
-Creating an instance of a _class_ is done by calling its [_constructor_][constructors] through the [`new` operator][new]. 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.
+Creating an instance of a _class_ is done by calling its [_constructor_][constructors] through the [`new` operator][new].
+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
 class Library {
@@ -15,7 +17,9 @@ class Library {
 var library = new Library();
 ```
 
-Like regular methods, constructors can have parameters. Constructor parameters are usually stored as (private) [fields][fields] to be accessed later, or else used in some one-off calculation. Arguments can be passed to constructors just like passing arguments to regular methods.
+Like regular methods, constructors can have parameters.
+Constructor parameters are usually stored as (private) [fields][fields] to be accessed later, or else used in some one-off calculation.
+Arguments can be passed to constructors just like passing arguments to regular methods.
 
 ```java
 class Building {
@@ -32,7 +36,8 @@ class Building {
 var largeBuilding = new Building(55, 6.2)
 ```
 
-Specifying a constructor is optional. If no constructor is specified, a parameterless constructor is generated by the compiler:
+Specifying a constructor is optional.
+If no constructor is specified, a parameterless constructor is generated by the compiler:
 
 ```java
 class Elevator {
@@ -42,7 +47,8 @@ class Elevator {
 var elevator = new Elevator();
 ```
 
-If fields have an initial value assigned to them, the compiler will output code in which the assignment is actually done inside the constructor. The following class declarations are thus equivalent (functionality-wise):
+If fields have an initial value assigned to them, the compiler will output code in which the assignment is actually done inside the constructor.
+The following class declarations are thus equivalent (functionality-wise):
 
 ```java
 class UsingFieldInitialization {

concepts/constructors/introduction.md

@@ -1,6 +1,8 @@
 # Introduction
 
-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.
+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
 class Library {
@@ -16,7 +18,9 @@ class Library {
 var library = new Library();
 ```
 
-Like regular methods, constructors can have parameters. Constructor parameters are usually stored as (private) fields to be accessed later, or else used in some one-off calculation. Arguments can be passed to constructors just like passing arguments to regular methods.
+Like regular methods, constructors can have parameters.
+Constructor parameters are usually stored as (private) fields to be accessed later, or else used in some one-off calculation.
+Arguments can be passed to constructors just like passing arguments to regular methods.
 
 ```java
 class Building {

concepts/exceptions/about.md

@@ -37,7 +37,8 @@ All exceptions in Java that inherit from `RuntimeException` are considered unche
 _Errors_ are exceptional conditions that are external to an application.
 An example of an error is the `OutOfMemoryError` which occurs when an application is trying to use more memory than is available on the system.
 
-Like unchecked exceptions, errors are not checked at compile-time. They are not usually thrown from application code.
+Like unchecked exceptions, errors are not checked at compile-time.
+They are not usually thrown from application code.
 
 All exceptions in Java that inherit from `Error` are considered errors.