Help File/Documentation Issues. (Discussion Only)

[water]

I do not think this is sensible as the documentation in section "function notes" clearly states: 

Quote

If a function uses the @error flag method, the flag should be checked immediately after the function returns as @error will be reset to 0 when entering the next function. No attempt to use or access the function return value should be made if the @error flag has been set as in that case the return value is generally undefined...

 

[jpm]

if the doc say failure = @error the @error must be check first so don't do any thing if the doc is correct

[argumentum]

4 hours ago, water said:

...if the @error flag has been set as in that case the return value is generally undefined...

un·de·fined /ˌəndəˈfīnd/  [adjective] not clear or defined. My English sucks.
So to be clear ( in my head ), if there is an error, don't trust the return, because there was an error.

 

3 hours ago, jpm said:

if the doc say failure = @error the @error must be check first so don't do any thing if the doc is correct

Well, then the doc is misleading. Actually, the documentation say that the 1st entry in the array is -1 if failure but the return is an integer. Hence the code and the explanation are in conflict. 

To wrap it up:
If there is an error, don't trust the return. Makes sense.
The return of a function that had an error will return nonsense, because there was an error and the error flag say that there was one.
If the expectation of a return is an integer and returns one, you get one back, but in this case the expectation is an array.
Say, in 

Func _NowDate()
    Local $tLocalTime = _Date_Time_GetLocalTime()
    If @error Then Return SetError(@error, @extended, "")
    Return _DateTimeFormat($tLocalTime.Year & "/" & $tLocalTime.Month & "/" & $tLocalTime.Day, 0)
EndFunc   ;==>_NowDate

on error here, the return is an empty string and that makes sense. And will not crash a script. I don't think that anyone checks for an error in this function, ever.

in this one:

Func _Date_Time_FileTimeToDOSDateTime($tFileTime)
    Local $aDate[2]
    Local $aCall = DllCall("kernel32.dll", "bool", "FileTimeToDosDateTime", "struct*", $tFileTime, "word*", 0, "word*", 0)
    If @error Then Return SetError(@error, @extended, $aDate)
    $aDate[0] = $aCall[2]
    $aDate[1] = $aCall[3]
    Return SetExtended($aCall[0], $aDate)
EndFunc   ;==>_Date_Time_FileTimeToDOSDateTime

is also good. If there is an error, the flag is set and returns an empty array.

All I propose is to have that type of consistency in  _Date_Time_GetTimeZoneInformation() ( as described in the help file )
Now given that the array may have nonsense ( from the DllCall ), to return an empty array like in this:

ConsoleWrite(@CRLF & Test()[0] & @TAB & @error & @CRLF & @CRLF)
Func Test()
    Return SetError(10, 0, __DateEmptyArray(8, -1))
EndFunc

; #FUNCTION# ====================================================================================================================
; Author ........: Paul Campbell (PaulIA)
; Modified.......: Gary Frost (gafrost); argumentum
; ===============================================================================================================================
Func _Date_Time_GetTimeZoneInformation()
    Local $aInfo[8] = [-1]
    Local $tTimeZone = DllStructCreate($tagTIME_ZONE_INFORMATION)
    Local $aCall = DllCall("kernel32.dll", "dword", "GetTimeZoneInformation", "struct*", $tTimeZone)
    If @error Then Return SetError(@error, @extended, __DateEmptyArray(8, -1))
    If $aCall[0] = -1 Then Return SetError(10, 0, __DateEmptyArray(8, -1))

    $aInfo[0] = $aCall[0]
    $aInfo[1] = DllStructGetData($tTimeZone, "Bias")
    $aInfo[2] = DllStructGetData($tTimeZone, "StdName")
    $aInfo[3] = __Date_Time_CloneSystemTime(DllStructGetPtr($tTimeZone, "StdDate"))
    $aInfo[4] = DllStructGetData($tTimeZone, "StdBias")
    $aInfo[5] = DllStructGetData($tTimeZone, "DayName")
    $aInfo[6] = __Date_Time_CloneSystemTime(DllStructGetPtr($tTimeZone, "DayDate"))
    $aInfo[7] = DllStructGetData($tTimeZone, "DayBias")
    Return $aInfo
EndFunc   ;==>_Date_Time_GetTimeZoneInformation

Func __DateEmptyArray($iSize, $v1stValue = "")
    Local $aArray[$iSize] = [$v1stValue]
    Return $aArray
EndFunc   ;==>__DateEmptyArray

would be best, because the array has a return from a DllCall, and may be "dirty" so, we return an empty array that satisfies the spirit of the function, the expected error as per the help file, and would not crash the script, as the cherry on top.

The only reason to keep it as is ( don't touch it ), is beyond me. And would happily welcome a response that obliterates my trend of thought. Am actually begging for one that does.