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

[Tom Rini]

On Wed, Oct 22, 2025 at 04:06:09PM +0200, Quentin Schulz wrote:
> 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 at konsulko.com>
> > > > ---
> > > > Cc: Heinrich Schuchardt <xypron.glpk at 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.

Yes. So while internally we do differentiate between failure of the
command and invalid syntax, we do not seem to populate that to the user.
I had misread one of the headers, so I'll rework the first patch.
Thanks!

-- 
Tom
-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 228 bytes
Desc: not available
URL: <https://lists.denx.de/pipermail/u-boot/attachments/20251022/89e07196/attachment.sig>