Help File/Documentation Issues. (Discussion Only)

[BinaryBrother]

Reference:
'?do=embed' frameborder='0' data-embedContent>>

According to Wikipedia, the range for 32bit signed int is (−2,147,483,648 to 2,147,483,647). Is it possible that I've found a slight typo in the documentation? - It states (−2,147,483,647 to 2,147,483,647)

Sources;

Wikipedia Link: http://en.wikipedia.org/wiki/Integer_%28computer_science%29

AutoIt Documentation SS: http://screencast.com/t/ajLijKiuO

Wikipedia SS: http://screencast.com/t/MBV8t8ICL97q

Edited January 26, 2014 by BinaryBrother

[Mat]

Yep, someone doesn't quite get 2s complement and assumed the range would be the same both sides. Very easy to check:

Local $i = 0
Local $iPrev = 0
Local $iStep = 10000000

While 1
    $iPrev = $i
    $i -= $iStep

    If StringLen(Hex($i)) <> StringLen(Hex(0)) Then
        $iStep = Int($iStep / 10)
        If $iStep = 0 Then ExitLoop

        $i = $iPrev
    EndIf
WEnd

ConsoleWrite($iPrev & @LF)

[mLipok]

  On 1/26/2014 at 3:40 AM, BinaryBrother said:

Sources;

Wikipedia Link: http://en.wikipedia.org/wiki/Integer_%28computer_science%29

AutoIt Documentation SS: http://screencast.com/t/ajLijKiuO

Wikipedia SS: http://screencast.com/t/MBV8t8ICL97q

 

It is not only in SetError but also in SetExtended.

Track Ticket: #2641

[BinaryBrother]

I kinda feel useful, for the first time in... 8 years? hahaha.

[Danyfirex]

This is a simple question about the Tutorial - Regular Expression, Part comparison using @ error, shows the comparison with == (which is used for strings with case sensitive), I think it would be better to leave with =. 

Well that's it. no big deal is just a small opinion. 

 

Look the examples in the tutorial.

 

http://www.autoitscript.com/autoit3/docs/tutorials/regexp/regexp.htm

 

regards

[mLipok]

I just noticed that it does not always "Return Value" are described fully.

Because such _ArraySort ()

  Quote

Return Value

Success: 1.
Failure: 0 and sets the @error flag to non-zero.

 

Specifies the value for Succes = 1 and Failure = 0

 

BUT in description for: _FileListToArray()

  Quote

Success: A one-dimensional array.

    $aArray[0] = Number of FilesFolders returned
    $aArray[1] = 1st FileFolder
    $aArray[2] = 2nd FileFolder
    $aArray[3] = 3rd FileFolder
    $aArray[n] = nth FileFolder
Failure: sets the @error flag to non-zero.

 

Where is information about the result of the function in case of "Failure"

I do some test:

#include <File.au3>
Local $aFiles = _FileListToArray('C:\notexist', '*.exe')
ConsoleWrite(VarGetType($aFiles) & @CRLF)
ConsoleWrite('==' & $aFiles & '==' & @CRLF)

>"C:\Program Files (x86)\AutoIt3\SciTE\AutoIt3Wrapper\AutoIt3Wrapper.exe" /run /prod /ErrorStdOut /in "Z:\TOOLs\Macro\test4.au3" /UserParams    
+>05:04:27 Starting AutoIt3Wrapper v.2.1.4.5 SciTE v.3.4.0.0   Keyboard:00000415  OS:WIN_7/Service Pack 1  CPU:X64 OS:X64    Environment(Language:0415)
>Running AU3Check (3.3.11.3)  from:C:\Program Files (x86)\AutoIt3  input:Z:\TOOLs\Macro\test4.au3
+>05:04:27 AU3Check ended.rc:0
>Running:(3.3.10.2):C:\Program Files (x86)\AutoIt3\autoit3.exe "Z:\TOOLs\Macro\test4.au3"    
--> Press Ctrl+Alt+F5 to Restart or Ctrl+Break to Stop
Int32
==0==
+>05:04:28 AutoIt3.exe ended.rc:0
+>05:04:28 AutoIt3Wrapper Finished..
>Exit code: 0    Time: 0.939

so the description in HelpFile I think it should look like this:

  Quote

Failure: 0 and sets the @error flag to non-zero.

 

What you think about this ?

 

After searching for "Failure: sets the @error"
I found 388 txt files for possible review and correct.

Are these all the files also require appropriate changes?

Edited March 26, 2014 by mLipok

[jpm]

In fact as the error checking of a UDF returning and array can be wrong  if tested as

If Not $aArray then ; error handling

It is better to use only

if @error The ; error handling

That the reason not to describ a 0 return

[jchd]

mlipok,

Not to lecture you, but as a more general rule and whatever language/context we talk about when something like a return value is not specified that doesn't mean it's a documentation hole. The item is simply not specified and shouldn't be relied on by mere testing what the function seems to do in a limited number of test cases.

For instance, imagine that this is a built-in function (whose code you can't have access to) and that this particular function makes tests on some conditions of the input array to perform one of many possible sort algorithms. It's quite possible that for coding efficiency the various branches inside the function would leave distinct return value. While this is unlikely in AutoIt because Return is an explicit and volontary statement, it isn't always the case in all contexts.

So when possible it's always better to make the specifications of the function (or whatever element of code) as simple as possible to keep them the most flexible for future changes, eventually. Take for instance the "result" of an automatically assigned increment in a For $i = 0 To 100 loop: in this case and without explicit mention that $i survives the loop and contains 101 after exiting it, one shouldn't rely on $i being 100 or 101. This detail is a side-effect of implementation choices and it's fair to leave that unspecified.

As an easy example, do you really know what this will print and do you really need to know that:

For $i = '0' To 'Z'
    ConsoleWrite("Iteration " & $i & @LF)
Next
ConsoleWrite(VarGetType($i) & " = " & $i & @LF)

EDIT: and what is printed when you replace 'Z' by '9' ?

Edited March 26, 2014 by jchd

[mLipok]

@jpm

Thanks for the clarification.
I think it can be considered as the "Best coding practice".

@jchd

Thank you for your valuable and informative comments, they changed my approach to certain issues.

[JohnOne]

  On 3/27/2014 at 3:40 AM, help file said:

_INetExplorerCapable

Converts a string to IE(Internet Explorer) capable line

Should that not really be Browser capable or do other browsers not work the same?

[mLipok]

  On 3/26/2014 at 6:25 AM, jpm said:

In fact as the error checking of a UDF returning and array can be wrong  if tested as

If Not $aArray then ; error handling

It is better to use only

if @error The ; error handling

That the reason not to describ a 0 return

 

so why for example in:

ControlGetHandle()

  Quote

 

Return Value

Success: the handle (HWND) value.

Failure: 0 and sets the @error flag to non-zero if no window matches the criteria.

[BrewManNH]

ControlGetHandle isn't a UDF function, so the return is different.

Sometimes the return values aren't consistent (in some of the UDFs) for all error conditions, but if you're looking at @error instead of a return value, you'll know whether there was an error or not.

[jchd]

mLipok,

You shouldn't expect the same level of consistancy in AutoIt, its built-in functions and standard UDFs on the one side and, say, C# and its standard libraries on the other side.

[Mat]

  On 3/27/2014 at 3:08 PM, jchd said:

mLipok,

You shouldn't expect the same level of consistancy in AutoIt, its built-in functions and standard UDFs on the one side and, say, C# and its standard libraries on the other side.

+1

You have to remember that in .NET it is trivial to change the build so it targets a different version of the framework, AutoIt we always have to balance changes between how useful they are and how many scripts they will break.

[jpm]

  On 3/27/2014 at 1:25 PM, mLipok said:

so why for example in:

ControlGetHandle()

I have personnaly get UDF return coherent, I can change the Builtin doc to be in conformance if suitable

[jchd]

To all,

My remark wasn't to mean that someone in particular did a bad job. Clearly, AutoIt (the core as well as the standard UDFs) has evolved slowy under freetime impulsion of various people and, lacking a complete and detailed development plan, it's no wonder that rigid and clever conventions proved hard to enforce. Also the need for backward compatibility -albeit not very strict- contributes to keep imperfect or non-consistent conventions to continue. A good example of that is the convention used here and there to carry the row count in the first element of 1D arrays, while other functions don't.

[mLipok]

I would like to be discussed the following question:

Whether each function, should contain

Func Examlpe()
.......
EndFunc

I notice that a lot of examples, is so precisely written, for example:
_ClipBoard_GetFormatName ()
ControlGetFocus ()
FileCopy ()

But not all, for example:
DriveGetLabel ()
_ArrayMinIndex ()
_DateAdd ()

Execute ()

 

Moreover, the latter are a bit confusing because they use the Local declaration outside the function.

[BrewManNH]

Normally, there's no reason to use a pseudo main function if the script is a standalone, but others have decided that the examples should contain a function that is used like a main function for the script. Not all the example scripts follow that format, and personally I see no reason to adapt them if they're working as they should. They're example scripts to demonstrate how to use the functions they're used in, and going through the help file merely to standardize some of them is more work than necessary.

As to global variables declared using local is a whole other can of worms that has been the cause of a lot of discussions that you can do a search on here, with very little agreement and you probably don't want to go down that road if you can avoid it. 

[Mat]

The other reason was that before multiple examples were added, they were done using Example1() Example2() etc. so had to be in functions to not interfere with each other.

It's always preferable to have code inside a function, so whenever guinness or myself or whoever else were modifying examples we wrote them that way. Changing every single example is a huge effort though for something that doesn't really change functionality or improve code that's only 20 lines long.

As to local at global level... Don't worry about it, just write all your code within functions and stay away from it all.

[mLipok]

Thank you for your response.

However, I would not approach this issue purely practical.
But also in terms - didactic.

The real question is whether a novice programmer reading HelpFile, acquires bad programming habits ?

by the way
A long time ago I finished didactic course, at the University of Silesia, out of here follows my approach to this matter.