Merge branch 'docs/clarify-storage-example-readmes_v6.0' into 'release/v6.0'

docs(storage): clarify example READMEs and when to use each (v6.0)

See merge request espressif/esp-idf!52038

examples/storage/nvs/nvs_bootloader/README.md

@@ -7,6 +7,11 @@ The purpose of this example is to show how to use the simplified, read-only API
 
 A very practical application of being able to access the NVS in the bootloader build would be faster device restoration, where-in the application stores the device's current state/configurations and post a reset it would read the NVS to restore the device's last state, without waiting for application to boot-up.
 
+## When to use this example
+
+- You need to read NVS data from the bootloader (before the app starts), e.g. for fast state restoration.
+- You want to use the simplified, read-only NVS bootloader API.
+
 ## Usage of this example:
 
 Simply compile it:

examples/storage/nvs/nvs_console/README.md

@@ -5,6 +5,11 @@
 
 This example demonstrates how to use Non-Volatile Storage (NVS) through an interactive console interface. It provides a set of commands to read, write, and manage data in NVS.
 
+## When to use this example
+
+- You want to inspect and modify NVS interactively at runtime (set/get/erase/list keys across namespaces).
+- You are debugging stored values or exploring NVS behavior without writing custom firmware.
+
 ## Hardware Required
 
 This example can run on any ESP32 family development board.

examples/storage/nvs/nvs_iteration/README.md

@@ -5,6 +5,11 @@
 
 This example showcases how to iterate and obtain info about NVS entries of a specific (or any) NVS datatype.
 
+## When to use this example
+
+- You need to enumerate NVS entries in code, filtered by type and/or namespace (`nvs_entry_find` / `nvs_entry_info`).
+- You are building tooling that discovers keys rather than reading known keys.
+
 Default "nvs" partition is first erased to allow for clean example run, followed by writing 2 sets of key value pairs of different types to NVS storage.
 After that, iteration is performed over the individual data types, as well as the generic `NVS_TYPE_ANY`, and relevant entry info gained from iteration is verbosely logged.
 
@@ -66,4 +71,4 @@ I (825) nvs_iteration_example: Iterated over 14 entries.
 I (825) nvs_iteration_example: Returning from app_main().
 I (835) main_task: Returned from app_main()
 ...
-```
+```

examples/storage/nvs/nvs_rw_blob/README.md

@@ -16,6 +16,11 @@ Detailed functional description of NVS and API is provided in [documentation](ht
 
 If not done already, consider checking simpler example *storage/nvs/nvs_rw_value*, that has been used as a starting point for preparing this one.
 
+## When to use this example
+
+- You need to store variable-length binary data (a blob), such as a table or struct, in NVS.
+- You want to see blob read-modify-write across reboots, including a button-triggered update.
+
 ## How to use example
 
 ### Hardware required

examples/storage/nvs/nvs_rw_value/README.md

@@ -15,6 +15,11 @@ Detailed functional description of NVS and API is provided in [documentation](ht
 
 Check another example *storage/nvs/nvs_rw_blob*, which shows how to read and write variable length binary data (blob).
 
+## When to use this example
+
+- You are new to NVS and want the simplest read/write of a single integer that survives reboots.
+- You need a starting template for storing small configuration/counter values.
+
 ## How to use example
 
 ### Hardware required

examples/storage/nvs/nvs_rw_value_cxx/README.md

@@ -9,6 +9,10 @@ This example demonstrates how to read and write a single integer value using NVS
 It is essentially the same as the nvs_rw_value example. The only difference is that it uses the C++ NVS handle API.
 Please see [nvs_rw_value README](../nvs_rw_value/README.md) for more details about this example.
 
+## When to use this example
+
+- You are writing C++ and want the RAII-style C++ NVS handle API instead of the C API.
+
 ## How to use example
 
 ### Hardware required

examples/storage/nvs/nvs_statistics/README.md

@@ -5,6 +5,11 @@
 
 This example demonstrates the usage of obtaining and interpreting statistics about the a given NVS partition, namely free/used/available/total entries and namespace count.
 
+## When to use this example
+
+- You want to measure NVS partition usage (free/used/available/total entries, namespace count) via `nvs_get_stats()`.
+- You need to understand blob storage overhead and fragmentation before sizing an NVS partition.
+
 The default "nvs" partition is first erased, then a mock string data configuration is written to 2 different namespaces, followed by checking the changed statistics and mainly the number of newly used NVS entries.
 
 Statistics obtained via [nvs_get_stats()](https://docs.espressif.com/projects/esp-idf/en/stable/esp32/api-reference/storage/nvs_flash.html#_CPPv413nvs_get_statsPKcP11nvs_stats_t) are the following:

examples/storage/nvs/nvsgen/README.md

@@ -52,3 +52,8 @@ I (387) example: Reading values from NVS done - all OK
 ```
 
 The logic of the example is contained in a [single source file](./main/nvsgen_example_main.c), and it should be relatively simple to match points in its execution with the log outputs above.
+
+## When to use this example
+
+- You want to pre-populate an NVS partition at build time from a CSV file and flash it with the app.
+- You need factory/default configuration baked into NVS without writing it from firmware.