Help File/Documentation Issues. (Discussion Only)

[mLipok]

Where in helpfile is said that standard AutoIt functions clears @error ?
I mean functions like Sleep() or MsgBox() ?

I checked the Function Notes and I do not see exact statement which I'm looking for.

Any body could point me to the proper statement ?

Edited April 10, 2021 by mLipok

[Melba23]

mLipok,

Look under "SetError":

  Quote

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

Expand  

M23

[mLipok]

  On 4/10/2021 at 3:26 PM, Melba23 said:

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

Expand  

After reading this text (many times today) , I still have the impression that this part of documentation was created only for "Standard UDF" or for "User Functions"

But not for "functions available in AutoIt".

It is not so clear for non English native speakers, especially for people who start learning programming, especially starting with AutoIt.

How this refer to :    Sleep() or MsgBox()  , or for FileWrite().... those function do not use SetError()

IMHO: I think two separate cases should be clearly described for "functions available in AutoIt" (internal) and "any user's function" (those defined in any au3 files).

 

Edited April 10, 2021 by mLipok

[Melba23]

mLipok,

From "Function Notes" (which specifically refer to "native" AutoIt funtions):

  Quote

...the flag should be checked immediately after the function returns as @error will be reset to 0 when entering the next function

Expand  

How much clearer do you want the Help file to be?

M23

[mLipok]

Reading this:

  Quote

Unless SetError() is called, then @error will remain 0 when the function ends

Expand  

I still had in my mind something like this:

  Quote

The @error will remain 0 when the function ends, unless internal/native functions set it. In case of user functions the @error will remain 0 unless SetError() will be used at it's ends.

Expand  

or something like this... maybe wrong worded due to my poor English skills.

[mLipok]

  On 4/10/2021 at 4:27 PM, Melba23 said:

the flag should be checked immediately after the function returns as @error will be reset to 0 when entering the next function

Expand  

When it states "after the function returns" I still have in my mind that "Return" function was used, what is not related to Native/Internal.

[Melba23]

mLipok,

For me it is quite clear that the "Function Notes" section refers solely to "native" AutoIt functions, not UDFs. You reach it via the link here:

  Quote

Below is a complete list of the functions available in AutoIt. Click on a function name for a detailed description.

See Function Notes for details on usage.

Expand  

Where does it mention UDFs there?

And ALL functions "return" when completed - it is not limited to the "Return" function within a UDF.

M23

[mLipok]

Yes I know.
But "Function Notes" is a basic resource of knowing how functions work, we shouldn't go back or look elsewhere for references, for such basic thing like how @error behaves.
This document itself should make this clear.
Or at least that is my opinion in this regard.

As to:

  On 4/10/2021 at 4:48 PM, Melba23 said:

And ALL functions "return" when completed - it is not limited to the "Return" function within a UDF.

Expand  

I know that Internal/Native function also returns. but this statements

  Quote

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

Expand  

For me as a non Native English speakers, this mean that the SetError() must be called to return @error <> 0 , and thus I state that it not cleary said about case when Native/Internal function is called.

For me as an advanced AutoIt programer this is known fact how it works, and I exactly know what you mean.

But as I said I was reading this part today, and I said to my self:

  Quote

Where there is said that Native/Internal function could set this value internally without SetError() ?

Expand  

Hence, my discussion on this thread, because I wanted someone less experienced, and at the same time a person who is not a native English speaker, to comment on this matter.

Because for me as an experienced programmer, but still poor English speaker, such a record in the documentation seemed strange and at least not complete, all the more for people with less experience it will be strange or confusing.

As this thread is called "Help File / Documentation Issues. (Discussion Only)" I wanted to ask and discuss if anyone else thinks similarly.

 

Edited April 10, 2021 by mLipok

[mLipok]

So @Melba23 I want to ask you (as a natvie English speaker and one of the most experienced AutoIt programer) is this following statement:

  On 4/10/2021 at 4:37 PM, mLipok said:

The @error will remain 0 when the function ends, unless internal/native functions set it. In case of user functions the @error will remain 0 unless SetError() will be used at it's ends.

Expand  

Correct and is more complex than this:

  Quote

Unless SetError() is called, then @error will remain 0 when the function ends

Expand  

?

or even ...  Could you reword my quoted statement to fit your's level of knowledge and experience ?

 

 

ps.
@Melba23 I hope I'm not raising your blood pressure

I just wanted to peacefully discuss some things that struck me as strange.

 

Edited April 10, 2021 by mLipok

[Melba23]

mLipok,

My suggestion would be that you:

1. Amend the opening phrase of the "Remarks" sections of the SetError and SetExtended pages to read:

  Quote

When entering a user-written function @error/@extended is set to 0

Expand  

2. Amend the "Function Notes" page "Success/failure indication" heading to read:

  Quote

Success/failure indication of internal AutoIt functions

Expand  

3. Add a final paragraph to the "Function Notes" page:

  Quote

Success/failure indication of user-written functions

The return value, @error, and @extended macros are normally set by the author using the Return/SetError/SetExtended functions within the code. See the documentation for the specific user-written library to determine the specific values that are used.

Expand  

How does that sound?

M23

[mLipok]

  On 4/10/2021 at 5:33 PM, Melba23 said:

How does that sound?

Expand  

I will follow your suggestions.
I hope that you will follow my changes on the internal AutoIt SVN and correct my possible mistakes, not only linguistic ones

mLipok

[mLipok]

In "Macro Reference - AutoIt Related"

Currently there is:

  Quote

@error

Status of the error flag. See the function SetError().

Expand  

 

  Quote

@extended

Extended function return - used in certain functions such as StringReplace().

Expand  

 

I would like to propose to change them in this way:

 

  Quote

@error

Status of the error flag. Can be set by internal AutoIt functions, and by user-written functions. See the function SetError().

Expand  

  Quote

@extended

Extended function return - used in certain functions. Can be set by internal AutoIt functions, and by user-written functions. See the function SetExtended().

Expand  

 

Edited April 10, 2021 by mLipok

[Melba23]

mLipok,

No, I do not agree with those suggestions - the current text is quite sufficient in my opinion. The Help file does not have to explain absolutely everything in great detail - it is big enough as it is.

M23

[mLipok]

In FunctionNotes in this part:

  On 4/10/2021 at 5:33 PM, Melba23 said:

Success/failure indication of internal AutoIt functions

Expand  

there is mentioned that:

  Quote

 @error will be reset to 0 when entering the next function

Expand  

what about mention that for internal AutoIt functions also @extended is reset to 0 ?
The information is only in SetExtended() which is for user-written functions.

Would you give any suggestions ?

[mLipok]

  On 4/10/2021 at 7:04 PM, Melba23 said:

No, I do not agree with those suggestions - the current text is quite sufficient in my opinion. The Help file does not have to explain absolutely everything in great detail - it is big enough as it is.

Expand  

Ok.
What about such smaller change:

  Quote

@extended

Extended function return - used in certain functions. See the function SetExtended().

Expand  

Instead current:

  Quote

@extended

Extended function return - used in certain functions such as StringReplace().

Expand  

 

[argumentum]

Func oops()
    Return SetError(23, 34, 45)
EndFunc
oops()
Sleep(1)
ConsoleWrite('+++ oops() returned @error = ' & @error & @TAB & '@extended = ' & @extended & @TAB)
ConsoleWrite("@AutoItVersion = " & @AutoItVersion & @CRLF)
Exit

;~ +++ oops() returned @error = 0   @extended = 0   @AutoItVersion = 3.2.0.1
;~ +++ oops() returned @error = 0   @extended = 0   @AutoItVersion = 3.3.14.5

 

Functions in AutoIt are first class objects. Among other things, that means you can assign a function to a variable, pass it around as an argument or return from another function.
Aside from certain specific scope-regarding declaration rules (being that the names of the built-in functions are reserved and of UDFs' can be overwritten only locally), the names of functions do not have special status in the language.

Therefore, as stated in the "Function notes", UDF or not, all Functions(), build-in or not, will return @error and @extended. Even sleep(), unless clearly specify, as _WinAPI_GetLastError() does.
The modification M23 suggest are in my mind clear. Tho I would mention the existence of SetError() and SetExtended() for functions in the "Function notes"

Other than that, I feel is ok.

[argumentum]

  On 4/10/2021 at 7:00 PM, mLipok said:

Currently there is:

  Quote

@error

Status of the error flag. See the function SetError().

Expand  

 

Expand  

...and reading SetError() it'll show, Related SetExtended().
So no need to change that.

I always tell new users to do the katas. A kata in AutoIt is go to the help file and run the examples. Copy the example elsewhere and do modifications. Doing so will give you great knowledge

Can't read up on a theme and become proficient. Users have to get dirty and read other ppl code and take the time to try and think.
As a wise person stated:  "thinking does not hurt, ... but it takes time"  

[argumentum]

..so I find a resurrected thread and ...yes, he is right. The example tutorial "Simple Notepad Automation" needs to change all the Win*() functions from searching TITLE to search CLASS.

Or add "WinTitleMatchMode" to make it work:

Run("notepad.exe")
WinWaitActive("Untitled - Notepad") ; for the english version, the title is historically as expected.
Send("This is some text.")
Opt("WinTitleMatchMode", 2) ; to find the now changed title
WinClose("Untitled - Notepad")
If Not WinWaitActive("Notepad", "Save", 5) Then Exit 4 ; window not found ?
;WinWaitActive("Notepad", "Do you want to save") ; When running under Windows XP
Sleep(1000) ; to give a chance to see something !
Send("!n")

 

Edited April 23, 2021 by argumentum

[TheXman]

Just a small typo.

In the Remarks section of the #OnAutoItStartRegister topic in the help file (chm and web), you will see the word "Dlobal".

[JockoDundee]

  On 6/3/2021 at 10:07 PM, TheXman said:

you will see the word "Dlobal"...

Expand  

Instead of painstakingly correcting this typo, I propose we take the time we would have used to fix the error, and invest it into the development of a Dlobal variable declaration with a novel scope/visibility, e.g. module/file level.

It would certainly come in handy