From 83a9b40d4da781e23735ecb6cfd56260272f7625 Mon Sep 17 00:00:00 2001
From: Cristian Maglie <c.maglie@arduino.cc>
Date: Tue, 12 Nov 2024 10:26:17 +0100
Subject: [PATCH] Updated docs

---
 docs/sketch-build-process.md | 31 +++++++++++++++--------------
 docs/sketch-specification.md | 38 +++++++++++++++++++++++-------------
 2 files changed, 40 insertions(+), 29 deletions(-)

diff --git a/docs/sketch-build-process.md b/docs/sketch-build-process.md
index 9f1f0067571..eda83a0cadd 100644
--- a/docs/sketch-build-process.md
+++ b/docs/sketch-build-process.md
@@ -52,19 +52,19 @@ generated for the path to each library dependency and appended to the
 If multiple libraries contain a file that matches the `#include` directive, the priority is determined by applying the
 following rules, one by one in this order, until a rule determines a winner:
 
-1. A library that has been specified using the [`--library` option](commands/arduino-cli_compile.md#options) of
-   `arduino-cli compile` wins against a library in other locations
+1. A library has been specified using the [`--library` option](commands/arduino-cli_compile.md#options) of
+   `arduino-cli compile`.
+1. A library is found in the `libraries` subfolder of the sketch.
 1. A library that is architecture compatible wins against a library that is not architecture compatible (see
    [**Architecture Matching**](#architecture-matching))
 1. A library with both [library name](#library-name-priority) and [folder name](#folder-name-priority) matching the
-   include wins
-1. A library that has better "library name priority" or "folder name priority" wins (see
-   [**Library Name Priority**](#library-name-priority) and [**Folder Name Priority**](#folder-name-priority))
-1. A library that is architecture optimized wins against a library that is not architecture optimized (see
-   [**Architecture Matching**](#architecture-matching))
-1. A library that has a better "location priority" wins (see [**Location Priority**](#location-priority))
-1. A library that has a folder name with a better score using the "closest-match" algorithm wins
-1. A library that has a folder name that comes first in alphanumeric order wins
+   include.
+1. A library has better "library name priority" or "folder name priority" (see
+   [**Library Name Priority**](#library-name-priority) and [**Folder Name Priority**](#folder-name-priority)).
+1. A library is architecture optimized (see [**Architecture Matching**](#architecture-matching)).
+1. A library has a better "location priority" (see [**Location Priority**](#location-priority)).
+1. A library has a folder name with a better score using the "closest-match" algorithm.
+1. A library has a folder name that comes first in alphanumeric order.
 
 ### Architecture Matching
 
@@ -126,14 +126,15 @@ The "location priority" is determined as follows (in order of highest to lowest
 
 1. The library is under a custom libraries path specified via the
    [`--libraries` option](commands/arduino-cli_compile.md#options) of `arduino-cli compile` (in decreasing order of
-   priority when multiple custom paths are defined)
-1. The library is under the `libraries` subfolder of the IDE's sketchbook or Arduino CLI's user directory
+   priority when multiple custom paths are defined).
+1. The library is under the `libraries` subfolder of the sketch.
+1. The library is under the `libraries` subfolder of the IDE's sketchbook or Arduino CLI's user directory.
 1. The library is bundled with the board platform/core
-   ([`{runtime.platform.path}/libraries`](platform-specification.md#global-predefined-properties))
+   ([`{runtime.platform.path}/libraries`](platform-specification.md#global-predefined-properties)).
 1. The library is bundled with the [referenced](platform-specification.md#referencing-another-core-variant-or-tool)
-   board platform/core
+   board platform/core.
 1. The library is bundled with the Arduino IDE (this location is determined by the Arduino CLI configuration setting
-   `directories.builtin.libraries`)
+   `directories.builtin.libraries`).
 
 #### Location priorities in Arduino Web Editor
 
diff --git a/docs/sketch-specification.md b/docs/sketch-specification.md
index 316787476c6..04e48d3c59e 100644
--- a/docs/sketch-specification.md
+++ b/docs/sketch-specification.md
@@ -72,6 +72,14 @@ Files added to the sketch via the Arduino IDE's **Sketch > Add File...** are pla
 The Arduino IDE's **File > Save As...** only copies the code files in the sketch root folder and the full contents of
 the `data` folder, so any non-code files outside the `data` folder are stripped.
 
+### `libraries` subfolder
+
+The `libraries` folder is used to store libraries compiled with the sketch. This folder should be used to store
+libraries that have been patched or to store libraries that are not available through the official library repository.
+
+- This feature is available since Arduino CLI 1.1.1
+- This feature is not yet available in Arduino IDE and Arduino Web Editor.
+
 ### Metadata
 
 #### `sketch.json`
@@ -118,25 +126,27 @@ Web Editor.
 ### Sketch file structure example
 
 ```
-Foo
+MotorController
 |_ arduino_secrets.h
-|_ Abc.ino
-|_ Def.cpp
-|_ Def.h
-|_ Foo.ino
-|_ Ghi.c
-|_ Ghi.h
-|_ Jkl.h
-|_ Jkl.S
+|_ motors.ino
+|_ defs.cpp
+|_ defs.h
+|_ MotorController.ino
+|_ someASM.h
+|_ someASM.S
 |_ sketch.yaml
 |_ data
 |  |_ Schematic.pdf
+|_ libraries
+|  |_ SomeLib
+|     |_ library.properties
+|     |_ src
+|        |_ SomeLib.h
+|        |_ SomeLib.cpp
 |_ src
-   |_ SomeLib
-      |_ library.properties
-      |_ src
-         |_ SomeLib.h
-         |_ SomeLib.cpp
+   |_ encoders
+      |_ encoders.h
+      |_ encoders.cpp
 ```
 
 ## Sketchbook