Make more improvements, including a new "about.md" document.

Author: josealonso

exercises/concept/tim-from-marketing-2/.docs/about.md

@@ -1,7 +1,7 @@
 # Instructions
 
 In this exercise you will be writing code to retrieve the factory employees.
-Employees have an ID, a name and a department name, like in the [tim-from-marketing](/exercises/concept/tim-from-marketing) exercise. 
+Employees have an ID, a name and a department name, like in the [tim-from-marketing](/exercises/concept/tim-from-marketing) exercise.
 The first field of an employee is always an integer number, but the name and the department name may be empty or null.
 The class constructor receives a parameter of type List<Employee>, which is populated in the tests.
 You will be writing two methods: `getEmployeeById(int)` and `getEmployeeDetailsById(int)`.
@@ -14,8 +14,7 @@ If the employee does not exist, returns an empty Optional instance.
 
 ## 2. Return the name and department of a given employee in a certain format
 
-Implement the `getEmployeeDetailsById(int)` method to return a string containing the id, the name and 
-the department of a given employee:
+Implement the `getEmployeeDetailsById(int)` method to return a string containing the id, the name and the department of a given employee:
 
 ```java
 getEmployeeDetailsById(1) => "1 - Tim - Marketing"

exercises/concept/tim-from-marketing-2/.docs/instructions.md

@@ -8,19 +8,37 @@ In other words, there is a chance the method returns "no value" at all.
 
 ## Creating an Optional<T> object
 
-Given an object of type Employee, an Optional<Employee> object is created as follows:
+Given an object of type Employee, an Optional<Employee> object can be created using the static [of][optional-of-javadoc] method:
 
 ```java
 Employee employee = new Employee();
 Optional<Employee> optionalEmployee = Optional.of(employee);
 ```
 
-`optionalEmployee` is a wrapper of `employee`.
+If the employee _may_ be not present, the static [ofNullable][optional-ofNullable-javadoc] method must be used:
 
-TBD: explain empty, present and get.
+```java
+Employee nullableEmployee = new Employee();
+Optional<Employee> nullableEmployee = Optional.ofNullable(employee);
+```
+
+`optionalEmployee` and `nullableEmployee` both are wrappers of an `Employee` object.
+
+## Basic methods
+
+If a value is present, the [isPresent][optional-isPresent-javadoc] method returns true and the [get][optional-get-javadoc] method returns the value.
+
+```java
+Employee employee = new Employee("Tim", 45);
+Optional<Employee> optionalEmployee = Optional.ofNullable(employee);
+boolean isThereAnEmployee = optionalEmployee.isPresent();  // true
+Employee employee = optionalEmployee.get();
+```
 
 ## Usage
 
+In order to throw an exception when the value is not present, the [orElseThrow][optional-orElseThrow-javadoc] method must be used.
+
 ```java
 public Optional<Employee> getEmployee(String name) {
     // Assume that getEmployeeByName returns an Optional<Employee>
@@ -29,7 +47,7 @@ public Optional<Employee> getEmployee(String name) {
 }
 ```
 
-If a default value must be returned, the `orElse` method can be used.
+If a default value must be returned, the [orElse][optional-orElse-javadoc] method can be used.
 
 ```java
 public Optional<Employee> getEmployee(String name) {
@@ -39,7 +57,7 @@ public Optional<Employee> getEmployee(String name) {
 }
 ```
 
-Other commonly used method is `ifPresentOrElse`, which is used to handle the case where the value is present and the case where the value is empty.
+Other commonly used method is [ifPresentOrElse][optional-ifPresentOrElse-javadoc], which is used to handle both cases with the same method: the case where the value is present and the case where the value is empty.
 
 ```java
 public Optional<Employee> getEmployee(String name) {
@@ -62,3 +80,11 @@ public Optional<Integer> getEmployeeAge(String name) {
                .orElse("No employee found");
 }
 ```
+
+[optional-of-javadoc]: https://docs.oracle.com/en/java/javase/21/docs/api/java.base/java/util/Optional.html#of(java.lang.Object)
+[optional-ofNullable-javadoc]: https://docs.oracle.com/en/java/javase/21/docs/api/java.base/java/util/Optional.html#ofNullable(java.lang.Object)
+[optional-get-javadoc]: https://docs.oracle.com/en/java/javase/21/docs/api/java.base/java/util/Optional.html#get()
+[optional-isPresent-javadoc]: https://docs.oracle.com/en/java/javase/21/docs/api/java.base/java/util/Optional.html#isPresent()
+[optional-orElse-javadoc]: https://docs.oracle.com/en/java/javase/21/docs/api/java.base/java/util/Optional.html#orElse(T)
+[optional-orElseThrow-javadoc]: https://docs.oracle.com/en/java/javase/21/docs/api/java.base/java/util/Optional.html#orElseThrow()
+[optional-ifPresentOrElse-javadoc]: https://docs.oracle.com/en/java/javase/21/docs/api/java.base/java/util/Optional.html#ifPresentOrElse(java.util.function.Consumer,java.lang.Runnable)

exercises/concept/tim-from-marketing-2/.docs/introduction.md

@@ -27,7 +27,7 @@ This Concepts Exercise's Concepts are:
 
 This Concept Exercise's prerequisites Concepts are:
 
-- `custom classes`.
+- `custom-classes`.
 - `lists`.
 - `generic-types`.
 

exercises/concept/tim-from-marketing-2/.meta/design.md

@@ -1,2 +1,2 @@
-connection.project.dir=../tim-from-marketing
+connection.project.dir=../..
 eclipse.preferences.version=1