[PATCH] manuals: document SPDX_CUSTOM_ANNOTATION_VARS

[michael.opdenacker@bootlin.com]

From: Michael Opdenacker <michael.opdenacker@bootlin.com>

Signed-off-by: Michael Opdenacker <michael.opdenacker@bootlin.com>
CC: Saul Wold <Saul.Wold@windriver.com>
CC: Joshua Watt <JPEWhacker@gmail.com>
---
 documentation/dev-manual/sbom.rst             |  3 +++
 .../migration-guides/release-notes-4.2.rst    |  9 ++++---
 documentation/ref-manual/variables.rst        | 26 +++++++++++++++++++
 3 files changed, 35 insertions(+), 3 deletions(-)

diff --git a/documentation/dev-manual/sbom.rst b/documentation/dev-manual/sbom.rst
index 448c071c55..f51d08f84d 100644
--- a/documentation/dev-manual/sbom.rst
+++ b/documentation/dev-manual/sbom.rst
@@ -63,6 +63,9 @@ generated files are available in ``tmp/deploy/spdx/MACHINE`` too, such as:
    (when :term:`SPDX_ARCHIVE_SOURCES` is set). Those are needed to fulfill
    "source code access" license requirements.
 
+See also the :term:`SPDX_CUSTOM_ANNOTATION_VARS` variable which allows
+to associate custom notes to a recipe.
+
 See the `tools page <https://spdx.dev/resources/tools/>`__ on the :term:`SPDX`
 project website for a list of tools to consume and transform the :term:`SPDX`
 data generated by the OpenEmbedded build system.
diff --git a/documentation/migration-guides/release-notes-4.2.rst b/documentation/migration-guides/release-notes-4.2.rst
index 4cf1974d4f..eb75dec6dc 100644
--- a/documentation/migration-guides/release-notes-4.2.rst
+++ b/documentation/migration-guides/release-notes-4.2.rst
@@ -45,9 +45,12 @@ New Features / Enhancements in 4.2
 
 -  New variables:
 
-   - :term:`VOLATILE_TMP_DIR` allows to specify
-     whether ``/tmp`` should be on persistent storage
-     or in RAM.
+   -  :term:`VOLATILE_TMP_DIR` allows to specify
+      whether ``/tmp`` should be on persistent storage
+      or in RAM.
+
+   -  :term:`SPDX_CUSTOM_ANNOTATION_VARS` allows to add
+      specific comments to the :term:`SPDX` description of a recipe.
 
 -  Rust improvements:
 
diff --git a/documentation/ref-manual/variables.rst b/documentation/ref-manual/variables.rst
index 62f28bd278..26ed1f29ae 100644
--- a/documentation/ref-manual/variables.rst
+++ b/documentation/ref-manual/variables.rst
@@ -7629,6 +7629,32 @@ system and gives an overview of their function and contents.
       (+ 0.07\% with the tested image), compared to just enabling
       :term:`SPDX_INCLUDE_SOURCES`.
 
+   :term:`SPDX_CUSTOM_ANNOTATION_VARS`
+      This option allows to associate `SPDX annotations
+      <https://spdx.github.io/spdx-spec/v2.3/annotations/>`__ to a recipe,
+      using the values of variables in the recipe::
+        
+         ANNOTATION1 = "First annotation for recipe"
+         ANNOTATION1 = "Second annotation for recipe"
+         SPDX_CUSTOM_ANNOTATION_VARS = "ANNOTATION1 ANNOTATION2"
+
+      This will add a new block to the recipe ``.sdpx.json`` output::
+
+         "annotations": [
+           {
+             "annotationDate": "2023-04-18T08:32:12Z",
+             "annotationType": "OTHER",
+             "annotator": "Tool: oe-spdx-creator - 1.0",
+             "comment": "ANNOTATION1=First annotation for recipe"
+           },
+           {
+             "annotationDate": "2023-04-18T08:32:12Z",
+             "annotationType": "OTHER",
+             "annotator": "Tool: oe-spdx-creator - 1.0",
+             "comment": "ANNOTATION2=Second annotation for recipe"
+           }
+         ],
+
    :term:`SPDX_INCLUDE_SOURCES`
       This option allows to add a description of the source files used to build
       the host tools and the target packages, to the ``spdx.json`` files in
-- 
2.34.1