[docs][PATCH] ref-manual: Clarify recommended operator for PROVIDES

[docs][PATCH] ref-manual: Clarify recommended operator for PROVIDES

[Joshua Watt]

Updates the documentation for PROVIDES so that it recommends "+="
instead of "=".

Signed-off-by: Joshua Watt <JPEWhacker@gmail.com>
---
 documentation/ref-manual/variables.rst | 16 +++++-----------
 1 file changed, 5 insertions(+), 11 deletions(-)

diff --git a/documentation/ref-manual/variables.rst b/documentation/ref-manual/variables.rst
index 4ce264813..2ea0cc36c 100644
--- a/documentation/ref-manual/variables.rst
+++ b/documentation/ref-manual/variables.rst
@@ -5915,23 +5915,17 @@ system and gives an overview of their function and contents.
       file ``eudev_3.2.9.bb``:
       ::
 
-         PROVIDES = "udev"
+         PROVIDES += "udev"
 
       The ``PROVIDES`` statement
       results in the "eudev" recipe also being available as simply "udev".
 
       .. note::
 
-         Given that a recipe's own recipe name is already implicitly in its
-         own PROVIDES list, it is unnecessary to add aliases with the "+=" operator;
-         using a simple assignment will be sufficient. In other words,
-         while you could write:
-         ::
-
-                 PROVIDES += "udev"
-
-
-         in the above, the "+=" is overkill and unnecessary.
+         A recipe's own recipe name (:term:`${PN}`) is always implicitly
+         included in the recipe aliases, so while using "+=" in the above
+         example may not be strictly necessary it is recommend to avoid
+         confusion.
 
       In addition to providing recipes under alternate names, the
       ``PROVIDES`` mechanism is also used to implement virtual targets. A
-- 
2.30.0

Re: [docs][PATCH] ref-manual: Clarify recommended operator for PROVIDES

[Robert P. J. Day]

On Tue, 19 Jan 2021, Joshua Watt wrote:

> Updates the documentation for PROVIDES so that it recommends "+="
> instead of "=".
>
> Signed-off-by: Joshua Watt <JPEWhacker@gmail.com>
> ---
>  documentation/ref-manual/variables.rst | 16 +++++-----------
>  1 file changed, 5 insertions(+), 11 deletions(-)
>
> diff --git a/documentation/ref-manual/variables.rst b/documentation/ref-manual/variables.rst
> index 4ce264813..2ea0cc36c 100644
> --- a/documentation/ref-manual/variables.rst
> +++ b/documentation/ref-manual/variables.rst
> @@ -5915,23 +5915,17 @@ system and gives an overview of their function and contents.
>        file ``eudev_3.2.9.bb``:
>        ::
>
> -         PROVIDES = "udev"
> +         PROVIDES += "udev"
>
>        The ``PROVIDES`` statement
>        results in the "eudev" recipe also being available as simply "udev".
>
>        .. note::
>
> -         Given that a recipe's own recipe name is already implicitly in its
> -         own PROVIDES list, it is unnecessary to add aliases with the "+=" operator;
> -         using a simple assignment will be sufficient. In other words,
> -         while you could write:
> -         ::
> -
> -                 PROVIDES += "udev"
> -
> -
> -         in the above, the "+=" is overkill and unnecessary.
> +         A recipe's own recipe name (:term:`${PN}`) is always implicitly
> +         included in the recipe aliases, so while using "+=" in the above
> +         example may not be strictly necessary it is recommend to avoid
                                                        recommended

rday

Re: [docs][PATCH] ref-manual: Clarify recommended operator for PROVIDES

[Quentin Schulz]

Hi Joshua,

On Tue, Jan 19, 2021 at 09:57:51AM -0600, Joshua Watt wrote:
> Updates the documentation for PROVIDES so that it recommends "+="
> instead of "=".
> 
> Signed-off-by: Joshua Watt <JPEWhacker@gmail.com>
> ---
>  documentation/ref-manual/variables.rst | 16 +++++-----------
>  1 file changed, 5 insertions(+), 11 deletions(-)
> 
> diff --git a/documentation/ref-manual/variables.rst b/documentation/ref-manual/variables.rst
> index 4ce264813..2ea0cc36c 100644
> --- a/documentation/ref-manual/variables.rst
> +++ b/documentation/ref-manual/variables.rst
> @@ -5915,23 +5915,17 @@ system and gives an overview of their function and contents.
>        file ``eudev_3.2.9.bb``:
>        ::
>  
> -         PROVIDES = "udev"
> +         PROVIDES += "udev"
>  
>        The ``PROVIDES`` statement
>        results in the "eudev" recipe also being available as simply "udev".
>  
>        .. note::
>  
> -         Given that a recipe's own recipe name is already implicitly in its
> -         own PROVIDES list, it is unnecessary to add aliases with the "+=" operator;
> -         using a simple assignment will be sufficient. In other words,
> -         while you could write:
> -         ::
> -
> -                 PROVIDES += "udev"
> -
> -
> -         in the above, the "+=" is overkill and unnecessary.
> +         A recipe's own recipe name (:term:`${PN}`) is always implicitly
> +         included in the recipe aliases, so while using "+=" in the above

s/included in the recipe aliases/included in its own PROVIDES list/ ?

Just a suggestion.

> +         example may not be strictly necessary it is recommend to avoid

s/recommend/recommended/

Thanks,
Quentin

Re: [docs][PATCH] ref-manual: Clarify recommended operator for PROVIDES

[Joshua Watt]

On 1/19/21 10:03 AM, Quentin Schulz wrote:
> Hi Joshua,
>
> On Tue, Jan 19, 2021 at 09:57:51AM -0600, Joshua Watt wrote:
>> Updates the documentation for PROVIDES so that it recommends "+="
>> instead of "=".
>>
>> Signed-off-by: Joshua Watt <JPEWhacker@gmail.com>
>> ---
>>   documentation/ref-manual/variables.rst | 16 +++++-----------
>>   1 file changed, 5 insertions(+), 11 deletions(-)
>>
>> diff --git a/documentation/ref-manual/variables.rst b/documentation/ref-manual/variables.rst
>> index 4ce264813..2ea0cc36c 100644
>> --- a/documentation/ref-manual/variables.rst
>> +++ b/documentation/ref-manual/variables.rst
>> @@ -5915,23 +5915,17 @@ system and gives an overview of their function and contents.
>>         file ``eudev_3.2.9.bb``:
>>         ::
>>   
>> -         PROVIDES = "udev"
>> +         PROVIDES += "udev"
>>   
>>         The ``PROVIDES`` statement
>>         results in the "eudev" recipe also being available as simply "udev".
>>   
>>         .. note::
>>   
>> -         Given that a recipe's own recipe name is already implicitly in its
>> -         own PROVIDES list, it is unnecessary to add aliases with the "+=" operator;
>> -         using a simple assignment will be sufficient. In other words,
>> -         while you could write:
>> -         ::
>> -
>> -                 PROVIDES += "udev"
>> -
>> -
>> -         in the above, the "+=" is overkill and unnecessary.
>> +         A recipe's own recipe name (:term:`${PN}`) is always implicitly
>> +         included in the recipe aliases, so while using "+=" in the above
> s/included in the recipe aliases/included in its own PROVIDES list/ ?
>
> Just a suggestion.

Hmm, yes. I was trying to avoid saying ${PN} was in PROVIDES because I 
though it wasn't, but I see that it is (using _prepend).


>
>> +         example may not be strictly necessary it is recommend to avoid
> s/recommend/recommended/
>
> Thanks,
> Quentin

[docs][PATCH v2] ref-manual: Clarify recommended operator for PROVIDES

[Joshua Watt]

Updates the documentation for PROVIDES so that it recommends "+="
instead of "=".

Signed-off-by: Joshua Watt <JPEWhacker@gmail.com>
---
 documentation/ref-manual/variables.rst | 15 ++++-----------
 1 file changed, 4 insertions(+), 11 deletions(-)

diff --git a/documentation/ref-manual/variables.rst b/documentation/ref-manual/variables.rst
index 4ce264813..1bbc5cbca 100644
--- a/documentation/ref-manual/variables.rst
+++ b/documentation/ref-manual/variables.rst
@@ -5915,23 +5915,16 @@ system and gives an overview of their function and contents.
       file ``eudev_3.2.9.bb``:
       ::
 
-         PROVIDES = "udev"
+         PROVIDES += "udev"
 
       The ``PROVIDES`` statement
       results in the "eudev" recipe also being available as simply "udev".
 
       .. note::
 
-         Given that a recipe's own recipe name is already implicitly in its
-         own PROVIDES list, it is unnecessary to add aliases with the "+=" operator;
-         using a simple assignment will be sufficient. In other words,
-         while you could write:
-         ::
-
-                 PROVIDES += "udev"
-
-
-         in the above, the "+=" is overkill and unnecessary.
+         A recipe's own recipe name (:term:`PN`) is always implicitly prepended
+         to `PROVIDES`, so while using "+=" in the above example may not be
+         strictly necessary it is recommended to avoid confusion.
 
       In addition to providing recipes under alternate names, the
       ``PROVIDES`` mechanism is also used to implement virtual targets. A
-- 
2.30.0