Re: [PATCH 2/3] doc: askenv: Reword and remove return value

[Quentin Schulz <quentin.schulz@cherry.de>]

On 10/22/25 3:49 PM, Tom Rini wrote:
> On Wed, Oct 22, 2025 at 11:28:15AM +0200, Quentin Schulz wrote:
>> Hi Tom,
>>
>> On 10/21/25 10:25 PM, Tom Rini wrote:
>>> With the addition of general text about how the return value is handled,
>>> remove the examples from the askenv documentation as they are all normal
>>> expected results.
>>>
>>> Signed-off-by: Tom Rini <trini@konsulko.com>
>>> ---
>>> Cc: Heinrich Schuchardt <xypron.glpk@gmx.de>
>>> ---
>>>    doc/usage/cmd/askenv.rst | 27 +++------------------------
>>>    1 file changed, 3 insertions(+), 24 deletions(-)
>>>
>>> diff --git a/doc/usage/cmd/askenv.rst b/doc/usage/cmd/askenv.rst
>>> index e2b3c5379aea..a8867ce4d266 100644
>>> --- a/doc/usage/cmd/askenv.rst
>>> +++ b/doc/usage/cmd/askenv.rst
>> [...]
>>> -Return Value of askenv command, when used without any other arguments:
>>> -
>>> -::
>>> -
>>> -    => askenv;echo $?
>>> -    askenv - get environment variables from stdin
>>> -
>>> -    Usage:
>>> -    askenv name [message] [size]
>>> -        - display 'message' and get environment variable 'name' from stdin (max 'size' chars)
>>> -    1
>>
>> Shouldn't that be -1 here to match the expected return value when the syntax
>> is incorrect?
>>
>> If it is 1, then it's a difference to the expected return value and thus
>> should be documented below?
> 
> This was included seemingly to include the built-in help message
> in-text. If desired, we should figure out how to do that automatically
> and for all commands.
> 

Agreed, it'd be awesome to extract the _usage part of U_BOOT_CMDs as 
summary for doc/usage/cmd/*.rst and _help part as the synopsis part so 
that they don't need to be kept in sync (at least that part).

> This is separate from what I see this morning right now of any invalid
> usage returning "1" and not "-1".
> 
> This is from sandbox build yesterday on top of tree:
> => loadm y y y y y y
> loadm - load binary blob from source address to destination address
> 
> Usage:
> loadm [src_addr] [dst_addr] [size]
>       - load a binary blob from one memory location to other from src_addr to dst_addr by size bytes
> => echo $?
> 1
> 

Then patch 1 is wrong? Or rather, what is moved in patch 1 is wrong?

"""
values are 0 on success, -1 on a usage related errors, i. e. invalid 
syntax and 1 on any other error.
"""

loadm y y y y y y would be an invalid syntax, meaning the return value 
is expected to be -1 according to the definition above.