[PATCH 1/1] doc: bitbake-user-manual-metadata: fix inherit_defer documentation

[Dawid Bijak <bijak.dawid@gmail.com>]

The documentation for inherit_defer contained the claim

"If VARNAME is going to be set, it needs to be set before the
inherit_defer statement is parsed"

which is incorrect and contradicts the purpose of inherit_defer.
The wrong claim is replaced with an example which demonstrates
the contrast between a plain defer statement and the inherit_defer
statement by using an override assignment placed after inherit_defer

Additionally the inline python expression examples have been
moved from the inherit_defer section up to the inherit section, since
they apply to both directives

Also add an anti-example showing that the previously documented
pattern of setting the inherited class name from an anonymous
Python function does not work with inherit_defer.

Signed-off-by: Dawid Bijak <bijak.dawid@gmail.com>
---
 .../bitbake-user-manual-metadata.rst          | 61 ++++++++++---------
 1 file changed, 32 insertions(+), 29 deletions(-)

diff --git a/doc/bitbake-user-manual/bitbake-user-manual-metadata.rst b/doc/bitbake-user-manual/bitbake-user-manual-metadata.rst
index 40cae6b05..38efe6b11 100644
--- a/doc/bitbake-user-manual/bitbake-user-manual-metadata.rst
+++ b/doc/bitbake-user-manual/bitbake-user-manual-metadata.rst
@@ -803,7 +803,17 @@ An advantage with the inherit directive as compared to both the
 :ref:`include <bitbake-user-manual/bitbake-user-manual-metadata:\`\`include\`\` directive>` and :ref:`require <bitbake-user-manual/bitbake-user-manual-metadata:\`\`require\`\` directive>`
 directives is that you can inherit class files conditionally. You can
 accomplish this by using a variable expression after the ``inherit``
-statement.
+statement, as in::
+
+   inherit ${@'classname' if condition else ''}
+
+Or::
+
+   inherit ${@bb.utils.contains('VARIABLE', 'something', 'classname', '', d)}
+
+In both cases, if the expression evaluates to an
+empty string, the statement does not trigger a syntax error because it
+becomes a no-op.
 
 For inheriting classes conditionally, using the :ref:`inherit_defer
 <ref-bitbake-user-manual-metadata-inherit-defer>` directive is advised as
@@ -827,39 +837,32 @@ the variable after the line is parsed will take effect. With the :ref:`inherit
 
 Here is an example::
 
-   inherit_defer ${VARNAME}
-
-If ``VARNAME`` is
-going to be set, it needs to be set before the ``inherit_defer`` statement is
-parsed. One way to achieve a conditional inherit in this case is to use
-overrides::
-
    VARIABLE = ""
-   VARIABLE:someoverride = "myclass"
-
-Another method is by using :ref:`anonymous Python
-<bitbake-user-manual/bitbake-user-manual-metadata:Anonymous Python Functions>`.
-Here is an example::
+   inherit_defer ${VARIABLE}
+   VARIABLE:someoverride = "someclass"
+
+:ref:`inherit_defer <ref-bitbake-user-manual-metadata-inherit-defer>`
+defers the evaluation of ``${VARIABLE}`` until the end of
+parsing. Assuming ``someoverride`` is in :term:`OVERRIDES`, ``${VARIABLE}``
+expands to ``someclass``, which is then inherited. Contrast this with a plain
+:ref:`inherit <ref-bitbake-user-manual-metadata-inherit>`, which would evaluate
+``${VARIABLE}`` immediately, before the ``VARIABLE:someoverride`` assignment
+is parsed. ``${VARIABLE}`` would expand to an empty string and the statement
+would become a no-op.
+
+Note that assigning the variable from an
+:ref:`anonymous Python function <bitbake-user-manual/bitbake-user-manual-metadata:Anonymous Python Functions>`
+does *not* work, because deferred inherits are resolved before anonymous
+Python functions run::
 
    python () {
-       if condition == value:
-           d.setVar('VARIABLE', 'myclass')
-       else:
-           d.setVar('VARIABLE', '')
+       if d.getVar('SOMETHING') == 'value':
+           d.setVar('VARIABLE', 'someotherclass')
    }
 
-Alternatively, you could use an inline Python expression in the
-following form::
-
-   inherit_defer ${@'classname' if condition else ''}
-
-Or::
-
-   inherit_defer ${@bb.utils.contains('VARIABLE', 'something', 'classname', '', d)}
-
-In all cases, if the expression evaluates to an
-empty string, the statement does not trigger a syntax error because it
-becomes a no-op.
+The conditional assignment of ``someotherclass`` has no effect on the
+``inherit_defer`` statement, which has already been resolved by the time
+the anonymous Python function runs.
 
 See also :term:`BB_DEFER_BBCLASSES` for automatically promoting classes
 ``inherit`` calls to ``inherit_defer``.
-- 
2.48.1