Report Help file errors here (Part 2)

[Melba23]

JohnOne,

Interesting - I have never used that function (I normally set @extended with SetError), but the documentation is very confusing as you say.

Testing the function makes me even more confused. It returns the value set in the "return value" parameter (with a default of 1) as can be seen here:

$iRet = SetExtended(5, 4)
ConsoleWrite(@extended & " - " & $iRet & @CRLF)

$iRet = SetExtended(5)
ConsoleWrite(@extended & " - " & $iRet & @CRLF)

but I cannot imagine why it should.  What purpose can it possibly serve?

Anyway, here is my suggestion for the Help file text:

expandcollapse popup

###Function###
SetExtended

###Description###
Manually set the value of the @extended macro.

###Syntax###
SetExtended ( code [, return value = 1 ] )


###Parameters###
@@ParamTable@@
code
    The required value (integer) to set into the @extended macro.
return value
    [optional] Return the value passed in the parameter.
@@End@@

###ReturnValue###
The value of the return value parameter (default = 1)


###Remarks###
When entering a function @extended is set to 0. Unless SetExtended() is called, then @extended will remain 0 when the function ends. This means that in order 

for @extended to be set after a function returns, it must be explicitly set in the function. This also means you may need to backup the status of @extended in 

a variable if you are testing it in a While-WEnd loop.
@extended is limited between the values of -2147483647 to 2147483647.


###Related###
SetError


###Example###
@@IncludeExample@@

Does that make it any clearer?

M23

[JohnOne]

The value of the return value parameter (default = 1)

 

 

It does.

I think

By default, none, however if the optional return value argument is passed, then the function will return that value.

 

Was meant to mean, when SetExtended is used like this.

$var = _Test() + @extended

Func _Test()
    Return SetExtended(3, 5)
EndFunc

Edited July 31, 2013 by JohnOne

[guinness]

I can see a use for SetExtended over SetError, I think...do I..erm...maybe!

[JohnOne]

I often use @error and @extended as int return values when instead of a small array when I need two or thee values from a function.

They're very handy macro's.

[guinness]

I often use @error and @extended as int return values when instead of a small array when I need two or thee values from a function.

They're very handy macro's.

But I guess you normally use SetError?

[JohnOne]

Yep, I only used SetExtended today, after like 3 years or something 

[AZJIO]

JohnOne

[czardas]

Testing the function makes me even more confused. It returns the value set in the "return value" parameter (with a default of 1) as can be seen here:

$iRet = SetExtended(5, 4)
ConsoleWrite(@extended & " - " & $iRet & @CRLF)

$iRet = SetExtended(5)
ConsoleWrite(@extended & " - " & $iRet & @CRLF)

but I cannot imagine why it should.  What purpose can it possibly serve?

 

I sometimes set the function return value to 1:- a method I copied from the Array.au3 UDF. I presume it is intended to indicate that a function performed successfully. I'm often wrong in my assumptions.

Edited July 31, 2013 by czardas

[guinness]

True or False is better. I dunno why AutoIt functions return 1 or 0, but it's not really an issue.

[czardas]

I prefer return values of 1 or 0. I think it's more flexible.

Edited July 31, 2013 by czardas

[MHz]

Testing the function makes me even more confused. It returns the value set in the "return value" parameter (with a default of 1) as can be seen here:

$iRet = SetExtended(5, 4)
ConsoleWrite(@extended & " - " & $iRet & @CRLF)

$iRet = SetExtended(5)
ConsoleWrite(@extended & " - " & $iRet & @CRLF)

but I cannot imagine why it should.  What purpose can it possibly serve?

 

That is ill use. $iRet is useless as you have no option to return it from a UDF. This is why $iRet is regarded as none in the help file as it is useless to use. This goes for the return of SetError as well. $iRet value should not be considered reliable to document as it serves no meaningful purpose.

Now, a general summary.

The old way when SetError used only 1 parameter and SetExtended did not exist was.

SetError(1)
Return 0

SetError always returned 1 (i.e. $iRet) so you could not append it to Return so it was limited if you wanted to return anything other then 1.

As a fix, SetError was extended to accept up to 3 parameters and SetExtended was introduced to do up to 2 parameters.

So you could now append to the end of Return.

Return SetError(2, 3, "string")
; or
Return SetExtended(3, 'string')

The return value (like $iRet above) of SetError or SetExtended is not used by Return in this case (and is still ill to consider the return value like $iRet). It is the parameters that are the return values, @extended and @error.

The question is, what do you focus on? To focus on a always 1 for SetError or SetExtended, or what the Return from the UDF does.

Mind you the always 1 is useless. Doing the below is useless

If SetError(1) Then ...

as there is nothing to gain from it.

If you change the none to some value in the help file then make sure that focus and clarity are of primary concern and that it is well, that return value is useless. It is the parameters that matter most. Notice how I kept referring to $iRet as the return instead of the parameter and this is precisely what you need to be careful in documenting. To try and avoid confusion.

Edit:

The parameter overrules the return value.

Edited July 31, 2013 by MHz

[JohnOne]

All that is true, and is also the ambiguity.

SetExtended() is a documented function, that function returns 1 if you do not pass it optional second parameter.

I realize that it's prime actual use is to pass it a second parameter in order to use it like so.

Func _Func()
     Return SetExtended(1, 5)
EndFunc

But I think it should be better documented that that is it's primary usage, and the return value of the UDF will be the second parameter.

In any case, SetExtended() returns 1, not "none" if second parameter is not set.

[Melba23]

MHz,

Thanks for that explanation - all suddenly becomes clear.

M23

[MHz]

JohnOne,

That is True.

 

Return Value

By default, 1, however, if the optional return value argument is passed, then the function will return that value.

 

The however following is vital information as the default 1 is usually unwanted if you want to set error and return 0 to flag failure.

Melba23,

I think I messed it up a bit. The default is confusing even today to explain.

Edited July 31, 2013 by MHz

[trancexx]

Return values of SetError() and SetExtended() should be docummented as undefined for cases when return value parameter is omitted. That's the whole thing and probably it's the most correct.

Documenting this type of information regarding these functions or other built-ins should be left to developers.

[JohnOne]

Here's how I'd put it

Return Value

Success - Sets @Extended to the value of first parameter and returns the second parameter passed, if no value is passed to the second parameter the return is the default of 1.

Failure - If SetExtended fails, the return value is the same as Success but @extended is not set

 

Failure

$var = _Test()
$exten = @extended
MsgBox(0,"_Test", "Return = " & $var & @CRLF & "@Extended = " & $exten)

$var = _Test2()
$exten = @extended
MsgBox(0,"_Test2", "Return = " & $var & @CRLF & "@Extended = " & $exten)


Func _Test()
    Return SetExtended("String", 5)
EndFunc

Func _Test2()
    Return SetExtended("String")
EndFunc

[Melba23]

JohnOne,

Let me try again:

###Function###
SetExtended

###Description###
Manually set the value of the @extended macro.

###Syntax###
SetExtended ( code [, return value = 1 ] )


###Parameters###
@@ParamTable@@
code
    The required value (integer) to set into the @extended macro.
return value
    [optional] The value to be returned by the function - defaults to 1 if no parameter used.
@@End@@

###ReturnValue###
The return value parameter (default = 1)


###Remarks###
When entering a function @extended is set to 0. Unless SetExtended() is called, then @extended will remain 0 when the function ends. This means that in order for @extended to be set after a function returns, it must be explicitly set in the function. This also means you may need to backup the status of @extended in a variable if you are testing it in a While-WEnd loop.
@extended is limited between the values of -2147483647 to 2147483647.


###Related###
SetError


###Example###
@@IncludeExample@@

and this as an example:

#include <Constants.au3>

$vRet = Example()

MsgBox($MB_SYSTEMMODAL, "", "Return value = " & $vRet & @CRLF & "Value of @extended is: " & @extended)

Func Example()
    Return SetExtended(10, "Return value")
EndFunc

How does that look now?

M23

[JohnOne]

"The value to be returned by the function - defaults to 1 if no parameter used."

Well I know what that means, but SetExtended is not always and does not have to be used in that fashion (Return SetExtended(.,.))

Ans so the function (UDF that it is used in) will not return the second parameter.

Func _Test()
    SetExtended(1, 5)
EndFunc

And essentially, there is no way to determine if SetExtended() fails, and it can with beginners I'm sure

EDIT: I'd suggest AU3Check catch an argument that would cause SetExtended to fail.

EDIT2: But I suppose that would not work if the argument were a variable.

Edited July 31, 2013 by JohnOne

[guinness]

Would you possibly mind doing the same for SetError?

[MHz]

...

Func _Test()
    SetExtended(1, 5)
EndFunc

...

You can use it like that and miss out on getting the 5 on return as you will get 0 instead. You need Return to get the return value.

This is how to get both

Return SetExtended(1, 5)

; or

SetExtended(1)
Return 5