Doc update2 (#143)

Some clean up

Author: ebariaux

Sources/EmbeddedSwift/Documentation.docc/CompilerDetails/ABI.md

@@ -30,7 +30,7 @@ The layout of Embedded Swift's class metadata is *different* from full Swift:
 - The **destructor pointer** is stored at **offset 1**. This function is invoked by Swift's deallocator when the class instance is destroyed.
 - The **ivar destroyer** is stored at **offset 2**. This function is invoked to destroy instance members when creation of the object is cancelled (e.g. in a failable initializer).
 - Lastly, the **vtable** is stored at **offset 3**: For each Swift class in the class's inheritance hierarchy, in order starting
-  from the root class and working down to the most derived class, the function pointers to the implementation of every method of the class in declaration order in stored.
+  from the root class and working down to the most derived class, the function pointers to the implementation of every method of the class in declaration order is stored.
 
 ### Witness Tables ABI
 

Sources/EmbeddedSwift/Documentation.docc/CompilerDetails/Status.md

@@ -16,7 +16,7 @@ Implementation status of compiler and language features in Embedded Swift, compa
 | Metatypes                                             | No, currently only allowed as unused arguments (type hints)                        |
 | Untyped throwing                                      | No, intentionally unsupported long-term (typed throwing should be used instead)    |
 | Weak references, unowned references                   | No                                                                                 |
-| Non-final generic class methods                       | No, intentionally unsupported long-term, see <[Embedded Swift -- Non-final generic methods](NonFinalGenericMethods.md)>|
+| Non-final generic class methods                       | No, intentionally unsupported long-term, see <doc:NonFinalGenericMethods>|
 | Parameter packs (variadic generics)                   | No, not yet supported                                                              |
 
 ## Embedded Standard Library Breakdown

Sources/EmbeddedSwift/Documentation.docc/GettingStarted/Introduction.md

@@ -22,7 +22,7 @@ It's also a good mental model to think of the Swift compiler in Embedded Swift m
 This results in properties that are a great fit for embedded software development:
 
 - **Small binaries** that can be as tiny as a few hundred bytes for "Hello World"-like programs (fully self-contained).
-- **No hidden runtime costs** – Embedded Swift's runtime library does not manage any data structures behind your back, is itself less than a kilobyte in size, and it eligible to be removed if unused.
+- **No hidden runtime costs** – Embedded Swift's runtime library does not manage any data structures behind your back, is itself less than a kilobyte in size, and is eligible to be removed if unused.
 - **No hidden allocations** which would cause unpredictable performance cliffs.
 - **Full C/C++ interoperability** to directly interact with existing C libraries and hardware-specific code, making it easy to integrate with vendor SDKs.
 - **Modern language features** like optionals, generics, and strong type safety are all available in Embedded Swift.
@@ -41,7 +41,7 @@ For a detailed introduction and motivation into Embedded Swift, please see "[A V
 
 The Swift toolchain has the ability to produce code for almost any standard ARM and RISC-V platform, and that makes Embedded Swift versatile and not limited to specific platforms or hardware devices. This way, Embedded Swift can potentially target many different microcontroller families and embedded devices.
 
-Boards with active community support include the Raspberry Pi Pico, various STM32 development boards, and several ESP32 variants, with more platforms being regularly added as the community grows.
+Boards with active community support include the Raspberry Pi Pico, various STM32 development boards, various nRF52840 based boards and several ESP32 variants, with more platforms being regularly added as the community grows.
 
 ## Interoperability with existing SDKs
 

Sources/EmbeddedSwift/Documentation.docc/GettingStarted/LanguageSubset.md

@@ -27,4 +27,4 @@ Note that there are no behavior changes in Embedded Swift compared to full Swift
 
 ## Further resources
 
-The above lists are describing features that are removed from Embedded Swift *by design*. Since Embedded Swift is currently an experimental preview, there might also be  features that are not yet implemented. See the in-development status at [Embedded Swift -- Status](EmbeddedSwiftStatus.md).
+The above lists are describing features that are removed from Embedded Swift *by design*. Since Embedded Swift is currently an experimental preview, there might also be  features that are not yet implemented. See the in-development status at <doc:Status>.

Sources/EmbeddedSwift/Documentation.docc/GuidedExamples/PicoGuide.md

@@ -23,7 +23,7 @@ $ export PICO_SDK_PATH=...       # location to your Pico SDK
 $ export PICO_TOOLCHAIN_PATH=... # location to the Arm Embedded Toolchain
 ```
 
-If you have the Wi-Fi enabled Pico W board instead of the regular Pico, note that you will need a slightly different setup described in the [Pico W example project](https://github.com/apple/swift-embedded-examples/tree/main/pico-w-blink-sdk), and just specifying `PICO_BOARD=pico_w` is not going to work.
+If you have the Wi-Fi enabled Pico W board instead of the regular Pico, note that you will need a slightly different setup described in the [Pico W example project](https://github.com/apple/swift-embedded-examples/tree/main/rpi-picow-blink-sdk), and just specifying `PICO_BOARD=pico_w` is not going to work.
 
 Install [CMake 3.29](https://cmake.org/) or newer.
 
@@ -48,8 +48,8 @@ bin/                                               libexec/
 
 ## Building a "blinky" embedded app
 
-The standard "Hello, World" in embedded development is a program that repeatedly blinks an LED. Let's build one. The following setup can be also found in [swift-embedded-examples](https://github.com/apple/swift-embedded-examples/blob/main/pico-blink-sdk/README.md), but we're going to show below that all you need is just three files.
-Let's create a new empty directory and prepare a simple structure for a CMake-based project that can be used on top the Pico SDK:
+The standard "Hello, World" in embedded development is a program that repeatedly blinks an LED. Let's build one. The following setup can be also found in [swift-embedded-examples](https://github.com/apple/swift-embedded-examples/blob/main/rpi-pico-blink-sdk/README.md), but we're going to show below that all you need is just three files.
+Let's create a new empty directory and prepare a simple structure for a CMake-based project that can be used on top of the Pico SDK:
 
 ```
 embedded-swift-tutorial

Sources/EmbeddedSwift/Documentation.docc/GuidedExamples/STM32BaremetalGuide.md

@@ -350,8 +350,14 @@ $ brew install stlink
 $ st-info --probe
 ... TODO
 $ brew install minicom
-$ minicom
-... TODO
+$ minicom --version
+minicom version 2.10 (compiled Feb 22 2025)
+Copyright (C) Miquel van Smoorenburg.
+
+This program is free software; you can redistribute it and/or
+modify it under the terms of the GNU General Public License
+as published by the Free Software Foundation; either version
+2 of the License, or (at your option) any later version.
 ```
 
 Then let's fetch the elf2hex tool:

Sources/EmbeddedSwift/Documentation.docc/SDKSupport/Baremetal.md

@@ -120,9 +120,9 @@ void ResetISR(void) {
 }
 ```
 
-Both these code snippets are not fully functional, they are only demonstrating the complexity of what the linker script and startup code need to do to initialize handle global variables.
+Both these code snippets are not fully functional, they are only demonstrating the complexity of what the linker script and startup code need to do to initialize global variables.
 
-Tip: If this handling is not done correctly, a typical symptom is that global variables "don't work", i.e. reading from them doesn't yield the right value, and writing to them doesn't persist. A good way to double check this is by using a debugging a dumping memory at runtime and checking if it matches the virtual memory layout of the ELF file.
+Tip: If this handling is not done correctly, a typical symptom is that global variables "don't work", i.e. reading from them doesn't yield the right value, and writing to them doesn't persist. A good way to double check this is by using a debugger, dumping memory at runtime and checking if it matches the virtual memory layout of the ELF file.
 
 ## Vector table and interrupts
 
@@ -167,7 +167,7 @@ To build an Embedded Swift baremetal project with SwiftPM, you will need a setup
 
 - Your main application target defined in Package.swift.
 - A helper C code helper target defined in Package.swift - this will contain your C startup code, vector table and possibly an assembly file.
-- Invoke `swift build` with a `--triple` argument that specifies.
+- Invoke `swift build` with a `--triple` argument that specifies the target CPU architecture and output object file format.
 - Use a `toolset.json` file that defines the common Swift and C compilation flags, and linking flags. This will e.g. enable the Embedded Swift mode when compiling Swift code, and point the linker at the right linker script.
 
 Example file structure:

Sources/EmbeddedSwift/Documentation.docc/SDKSupport/IntegrateWithPico.md

@@ -6,8 +6,8 @@ Setting up a project that can seamlessly use C APIs from the Pico SDK.
 
 Development for [Raspberry Pi Pico and Pico W](https://www.raspberrypi.com/products/raspberry-pi-pico/) normally uses the [Pico SDK](https://github.com/raspberrypi/pico-sdk) and the vendor provides several [sample projects in the pico-examples repository](https://github.com/raspberrypi/pico-examples). The SDK and sample project setup is described in:
 
-- https://www.raspberrypi.com/documentation/microcontrollers/c_sdk.html#sdk-setup
-- https://datasheets.raspberrypi.com/pico/getting-started-with-pico.pdf
+- [https://www.raspberrypi.com/documentation/microcontrollers/c_sdk.html#sdk-setup](https://www.raspberrypi.com/documentation/microcontrollers/c_sdk.html#sdk-setup)
+- [https://datasheets.raspberrypi.com/pico/getting-started-with-pico.pdf](https://datasheets.raspberrypi.com/pico/getting-started-with-pico.pdf)
 
 Before trying to use Swift with the Pico SDK, make sure your environment works and can build the provided C/C++ sample projects.
 

Sources/EmbeddedSwift/Documentation.docc/SDKSupport/IntegratingWithPlatforms.md

@@ -66,7 +66,7 @@ For detailed instructions on integrating with the Raspberry Pi Pico SDK, see <do
 
 ### ESP32
 
-For ESP microcontrollers using the ESP-IDF framework, see <doc:IntegrateWithESP>. Note that only chips based on RISC-V architecture (e.g. ESP32-C3, ESP32-C6, ESP32-P4) are supported with Embedded Swift. The Xtensa ISA (used in e.g. ESP8266 or ESP32-S2 and ESP32-S3).
+For ESP microcontrollers using the ESP-IDF framework, see <doc:IntegrateWithESP>. Note that only chips based on RISC-V architecture (e.g. ESP32-C3, ESP32-C6, ESP32-P4) are supported with Embedded Swift. The Xtensa ISA (used in e.g. ESP8266 or ESP32-S2 and ESP32-S3) is not supported.
 
 ### STM32