[gnome-continuous-yocto/gnomeostree-3.28-rocko: 2891/8267] bitbake: bitbake-user-manual: Added examples for using overrides with functions.

[Emmanuele Bassi <ebassi src gnome org>]

commit 7ab459d4b5a441c6c50c9579f89c295d56865f32
Author: Scott Rifenbark <srifenbark gmail com>
Date:   Wed Sep 21 15:30:14 2016 -0700

    bitbake: bitbake-user-manual: Added examples for using overrides with functions.
    
    Fixes [YOCTO #10296]
    
    This adds some bits clarifying you can append and prepend to
    functions.  Added a bit to the introduction paragraph of the
    "Appending and Prepending (Override Style Syntax)" section to
    note that you can do this.  Referenced some new examples.
    
    In the "Shell Functions" section I added an example.  In the
    "BitBake Style Python Functions" section I also added an example.
    
    (Bitbake rev: 6e6b7e10e04fdb94b59bd2ead3ccb79c899c7458)
    
    Signed-off-by: Scott Rifenbark <srifenbark gmail com>
    Signed-off-by: Richard Purdie <richard purdie linuxfoundation org>

 .../bitbake-user-manual-metadata.xml               |  117 +++++++++++++++++--
 1 files changed, 104 insertions(+), 13 deletions(-)
---
diff --git a/bitbake/doc/bitbake-user-manual/bitbake-user-manual-metadata.xml 
b/bitbake/doc/bitbake-user-manual/bitbake-user-manual-metadata.xml
index 47691af..82094b8 100644
--- a/bitbake/doc/bitbake-user-manual/bitbake-user-manual-metadata.xml
+++ b/bitbake/doc/bitbake-user-manual/bitbake-user-manual-metadata.xml
@@ -277,6 +277,15 @@
                     override syntax.
                 </note>
             </para>
+
+            <para>
+                It is also possible to append and prepend to shell
+                functions and BitBake-style Python functions.
+                See the
+                "<link linkend='shell-functions'>Shell Functions</link>" and
+                "<link linkend='bitbake-style-python-functions'>BitBake Style Python Functions</link>
+                sections for examples.
+            </para>
         </section>
 
         <section id='removing-override-style-syntax'>
@@ -1090,6 +1099,56 @@
                 such as <filename>dash</filename>.
                 You should not use Bash-specific script (bashisms).
             </para>
+
+            <para>
+                Overrides and override-style operators like
+                <filename>_append</filename> and
+                <filename>_prepend</filename> can also be applied to
+                shell functions.
+                Most commonly, this application would be used in a
+                <filename>.bbappend</filename> file to modify functions in
+                the main recipe.
+                It can also be used to modify functions inherited from
+                classes.
+            </para>
+
+            <para>
+                As an example, consider the following:
+                <literallayout class='monospaced'>
+     do_foo() {
+         bbplain first
+         fn
+     }
+
+     fn_prepend() {
+         bbplain second
+     }
+
+     fn() {
+         bbplain third
+     }
+
+     do_foo_append() {
+         bbplain fourth
+     }
+                </literallayout>
+                The output from <filename>do_foo</filename>
+                results in the following:
+                <literallayout class='monospaced'>
+     recipename do_foo: first
+     recipename do_foo: second
+     recipename do_foo: third
+     recipename do_foo: fourth
+                </literallayout>
+                <note>
+                    Overrides and override-style operators can
+                    be applied to any shell function, not just
+                    <link linkend='tasks'>tasks</link>.
+                </note>
+                You can use the <filename>bitbake -e</filename>&nbsp;<replaceable>recipename</replaceable>
+                command to view the final assembled function
+                after all overrides have been applied.
+            </para>
         </section>
 
         <section id='bitbake-style-python-functions'>
@@ -1114,19 +1173,51 @@
                 Also in these types of functions, the datastore ("d")
                 is a global variable and is always automatically
                 available.
-           </para>
-
-           <note>
-                Variable expressions (e.g. <filename>${X}</filename>) are no
-                longer expanded within Python functions.
-                This behavior is intentional in order to allow you to freely
-                set variable values to expandable expressions without having
-                them expanded prematurely.
-                If you do wish to expand a variable within a Python function,
-                use <filename>d.getVar("X", True)</filename>.
-                Or, for more complicated expressions, use
-                <filename>d.expand()</filename>.
-           </note>
+                <note>
+                    Variable expressions (e.g. <filename>${X}</filename>)
+                    are no longer expanded within Python functions.
+                    This behavior is intentional in order to allow you
+                    to freely set variable values to expandable expressions
+                    without having them expanded prematurely.
+                    If you do wish to expand a variable within a Python
+                    function, use <filename>d.getVar("X", True)</filename>.
+                    Or, for more complicated expressions, use
+                    <filename>d.expand()</filename>.
+                </note>
+            </para>
+
+            <para>
+                Similar to shell functions, you can also apply overrides
+                and override-style operators to BitBake-style Python
+                functions.
+            </para>
+
+            <para>
+                As an example, consider the following:
+                <literallayout class='monospaced'>
+     python do_foo_prepend() {
+         bb.plain("first")
+     }
+
+     python do_foo() {
+         bb.plain("second")
+     }
+
+     python do_foo_append() {
+         bb.plain("third")
+     }
+                </literallayout>
+                The output from <filename>do_foo</filename> results
+                in the following:
+                <literallayout class='monospaced'>
+     recipename do_foo: first
+     recipename do_foo: second
+     recipename do_foo: third
+                </literallayout>
+                You can use the <filename>bitbake -e</filename>&nbsp;<replaceable>recipename</replaceable>
+                command to view the final assembled function
+                after all overrides have been applied.
+            </para>
         </section>
 
         <section id='python-functions'>