fix: improve docs to align with tests (#925)

* fix: improve docs to align with tests

* tests: fix closing bracket.

Author: vaeng

Diff for: concepts/pointers/about.md

@@ -13,9 +13,10 @@ With modern C++ there are also _smart pointers_, the basic type is not smart at
 
 Before digging into the details, it's worth understanding the use of _pointers_.
 _Pointers_ are a way to share an object's address with other parts of our program, which is useful for two major reasons:
+
 1. Like _references_, pointers avoid copies and help to reduce the resource-footprint of your program.
-2. Unlike _references_, pointers can be reassigned to different objects.
-3. Pointers can also point to a null value, to indicate, that they currently do not point to any object.
+1. Unlike _references_, pointers can be reassigned to different objects.
+1. Pointers can also point to a null value, to indicate, that they currently do not point to any object.
 
 ## General Syntax
 
@@ -48,10 +49,10 @@ _Pointer arithmetic_ allows you to perform arithmetic operations on pointers, wh
 Adding an integer to a pointer makes it point to a different element.
 
 ```cpp
-// Stargate addresses
-int gateAddresses[] = {462, 753, 218, 611, 977};
-// 'ptr' points to the first element of 'gateAddresses'
-int* ptr{gateAddresses}; 
+// Stargate Coordinate Code
+int gateCode[] = {462, 753, 218, 611, 977};
+// 'ptr' points to the first element of 'gateCode'
+int* ptr{&gateCode[0]};
 // Accesses the third Stargate address through pointer arithmetic
 int dialedAddress{*(ptr + 2)}; 
 // Chevron encoded! Dialing Stargate address:
@@ -80,10 +81,13 @@ struct Superhero {
     std::string superpower;
 };
 
-Superhero* dianaPrince = new Superhero;
+Superhero wonder_woman{};
+Superhero* dianaPrince = &wonder_woman;
 dianaPrince->superpower = "Lasso of Truth";
+
 // Using the -> operator to access member variable superpower:
 std::cout << "Wonder Woman, possesses the mighty " << dianaPrince->superpower;
+
 // Memory cleanup:
 delete dianaPrince; 
 ```
@@ -127,6 +131,5 @@ It is your responsibility to detect these cases and ensure those pointers are su
 In older code, you might encounter two alternatives to `nullptr`.
 Firstly, the literal `0` is specifically interpreted as a null value for pointers, though it's the only scenario where an integral literal can be assigned to a pointer.
 Secondly, the `preprocessor macro` `NULL`, inherited from C and defined in the `<cstddef>` header, is another representation of a null pointer, though its usage is less common in modern C++ code.
-~~~~
-
 [ariane-flight-v88]: https://en.wikipedia.org/wiki/Ariane_flight_V88
+~~~~

Diff for: concepts/pointers/introduction.md

@@ -13,9 +13,10 @@ With modern C++ there are also _smart pointers_, the basic type is not smart at
 
 Before digging into the details, it's worth understanding the use of _pointers_.
 _Pointers_ are a way to share an object's address with other parts of our program, which is useful for two major reasons:
+
 1. Like _references_, pointers avoid copies and help to reduce the resource-footprint of your program.
-2. Unlike _references_, pointers can be reassigned to different objects.
-3. Pointers can also point to a null value, to indicate, that they currently do not point to any object.
+1. Unlike _references_, pointers can be reassigned to different objects.
+1. Pointers can also point to a null value, to indicate, that they currently do not point to any object.
 
 ## General Syntax
 
@@ -48,10 +49,10 @@ _Pointer arithmetic_ allows you to perform arithmetic operations on pointers, wh
 Adding an integer to a pointer makes it point to a different element.
 
 ```cpp
-// Stargate addresses
-int gateAddresses[] = {462, 753, 218, 611, 977};
-// 'ptr' points to the first element of 'gateAddresses'
-int* ptr{gateAddresses}; 
+// Stargate Coordinate Code
+int gateCode[] = {462, 753, 218, 611, 977};
+// 'ptr' points to the first element of 'gateCode'
+int* ptr{&gateCode[0]};
 // Accesses the third Stargate address through pointer arithmetic
 int dialedAddress{*(ptr + 2)}; 
 // Chevron encoded! Dialing Stargate address:
@@ -79,8 +80,8 @@ The `->` operator is used to access the member variable `superpower`, showcasing
 struct Superhero {
     std::string superpower;
 };
-
-Superhero* dianaPrince = new Superhero;
+Superhero wonder_woman{};
+Superhero* dianaPrince = &wonder_woman;
 dianaPrince->superpower = "Lasso of Truth";
 // Using the -> operator to access member variable superpower:
 std::cout << "Wonder Woman, possesses the mighty " << dianaPrince->superpower;
@@ -95,5 +96,3 @@ Pointers offer the flexibility of changing their target object and can be assign
 However, this flexibility introduces risks, such as dereferencing null pointers or creating dangling pointers.
 References, on the other hand, cannot be null and are bound to valid objects upon creation, avoiding these risks.
 Given their safer nature, references should be preferred over pointers unless the additional functionalities provided by pointers are necessary.
-
-[ariane-flight-v88]: https://en.wikipedia.org/wiki/Ariane_flight_V88

Diff for: exercises/concept/speedywagon/.docs/instructions.md

@@ -8,10 +8,10 @@ However, in recent times, the sensors that track Pillar Men activities are malfu
 The Foundation's systems are old, and the code interacts with a legacy C++ library that cannot be updated.
 Your task is to implement four core functions that monitor Pillar Men sensor activity using an old-fashioned pointer-based library.
 
-The Foundation's operations rely on you.
-
-## 0. The Sensor Environment (`pillar_men_sensor`)
+As a modern C++ engineer, you’d prefer using smart pointers, but alas, legacy code demands respect for the old ways.
+The fate of humanity may rest on these pointers, so proceed carefully, and may the Hamon energy guide you.
 
+~~~~exercism/note
 As sensor readings can be huge, we supply a mockup _struct_ that is used in the actual library.
 The code has already been implemented in the header file for you.
 
@@ -22,20 +22,17 @@ struct pillar_men_sensor {
     std::vector<int> data{};
 };
 ```
+~~~~
 
 ## 1. Check Sensor Connection (`connection_check`)
 
 Your first task is to ensure that the Pillar Men sensor is connected properly.
 We can't have false alarms triggered by disconnected sensors.
 You will write a function `connection_check`, which tests if the sensor's pointer is valid by checking for `nullptr`.
 
-### Task
-
 - Define a function that accepts a pointer a a `pillar_men_sensor` _struct_.
 - The function should return `true` if the sensor pointer is not null, and `false` otherwise.
 
-### Example
-
 ```cpp
 pillar_men_sensor* sensor{nullptr};
 bool isConnected = connection_check(sensor);
@@ -47,14 +44,10 @@ bool isConnected = connection_check(sensor);
 Pillar Men are lurking in the shadows, and we need to know if sensors have detected any activity.
 You will write the `activity_counter` function, which takes in an array of sensors and a capacity indicating the number of sensors in the array.
 
-### Task
-
 - Define a function that accepts a pointer to the first element of an array and the arrays capacity.
 - Use pointer arithmetic to loop through the sensor array and accumulate the activity readings.
 - Return the accumulated activity.
 
-### Example
-
 ```cpp
 pillar_men_sensor sensor_array[3] = {{0}, {101}, {22}};
 int totalActivity = activity_counter(sensor_array, 3);
@@ -67,14 +60,10 @@ Not every sensor should trigger an alarm unless there’s real danger.
 The `alarm_control` function ensures that a sensor only triggers an alarm if its activity level is greater than 0.
 This function should also check for null sensors to prevent system crashes.
 
-### Task
-
 - Define a function that accepts the pointer to a `pillar_men_sensor`.
 - The function should first check for a `nullptr` sensor. If the sensor is `nullptr`, return `false`.
 - If the sensor is valid and its activity is greater than 0, return `true`; otherwise, return `false`.
 
-### Example
-
 ```cpp
 pillar_men_sensor db{9008, "songokunoie", {7, 7, 7}};
 bool alarm = alarm_control(&db);
@@ -87,19 +76,9 @@ In this task, you will implement the `uv_alarm` function to determine whether an
 The `uv_alarm` function should use the provided `uv_light_heuristic` function, which operates on a vector of data and returns a value based on certain thresholds.
 This is a mockup version of the complex code that will run during production, please don't change the interface.
 
-### Task
-
 Define the `uv_alarm` function in the `speedywagon` namespace. It should:
 
 - Take a pointer to a `pillar_men_sensor` _struct_ as its parameter.
 - Return `false` if the sensor pointer is null.
 - Call the `uv_light_heuristic` function, passing the address of the sensor's `data` array.
 - Return `true` if the value returned by `uv_light_heuristic` is greater than the `sensor->activity` level, otherwise return `false`.
-
-## Wrapping Up
-
-You’ve been entrusted with an essential task for the Speedywagon Foundation.
-By testing for valid sensor connections, counting activity, and implementing alarm controls, you’ve ensured that the Foundation's battle against the Pillar Men can continue uninterrupted.
-
-As a modern C++ engineer, you’d prefer using smart pointers, but alas, legacy code demands respect for the old ways.
-The fate of humanity may rest on these pointers, so proceed carefully, and may the Hamon energy guide you.

Diff for: exercises/concept/speedywagon/.docs/introduction.md

@@ -13,9 +13,10 @@ With modern C++ there are also _smart pointers_, the basic type is not smart at
 
 Before digging into the details, it's worth understanding the use of _pointers_.
 _Pointers_ are a way to share an object's address with other parts of our program, which is useful for two major reasons:
+
 1. Like _references_, pointers avoid copies and help to reduce the resource-footprint of your program.
-2. Unlike _references_, pointers can be reassigned to different objects.
-3. Pointers can also point to a null value, to indicate, that they currently do not point to any object.
+1. Unlike _references_, pointers can be reassigned to different objects.
+1. Pointers can also point to a null value, to indicate, that they currently do not point to any object.
 
 ## General Syntax
 
@@ -48,10 +49,10 @@ _Pointer arithmetic_ allows you to perform arithmetic operations on pointers, wh
 Adding an integer to a pointer makes it point to a different element.
 
 ```cpp
-// Stargate addresses
-int gateAddresses[] = {462, 753, 218, 611, 977};
-// 'ptr' points to the first element of 'gateAddresses'
-int* ptr{gateAddresses}; 
+// Stargate Coordinate Code
+int gateCode[] = {462, 753, 218, 611, 977};
+// 'ptr' points to the first element of 'gateCode'
+int* ptr{&gateCode[0]};
 // Accesses the third Stargate address through pointer arithmetic
 int dialedAddress{*(ptr + 2)}; 
 // Chevron encoded! Dialing Stargate address:
@@ -79,8 +80,8 @@ The `->` operator is used to access the member variable `superpower`, showcasing
 struct Superhero {
     std::string superpower;
 };
-
-Superhero* dianaPrince = new Superhero;
+Superhero wonder_woman{};
+Superhero* dianaPrince = &wonder_woman;
 dianaPrince->superpower = "Lasso of Truth";
 // Using the -> operator to access member variable superpower:
 std::cout << "Wonder Woman, possesses the mighty " << dianaPrince->superpower;
@@ -95,5 +96,3 @@ Pointers offer the flexibility of changing their target object and can be assign
 However, this flexibility introduces risks, such as dereferencing null pointers or creating dangling pointers.
 References, on the other hand, cannot be null and are bound to valid objects upon creation, avoiding these risks.
 Given their safer nature, references should be preferred over pointers unless the additional functionalities provided by pointers are necessary.
-
-[ariane-flight-v88]: https://en.wikipedia.org/wiki/Ariane_flight_V88