compiler behavior and help text inconsistent

[Axolotl]

I'm surely thinking too much but i'm always defensive when programming. I.e. if a procedure has a return value, then I also observe it accordingly.
This brings me to the Topic: Dealing with return values when compiler and help are different, or better they are not really different, but only differently accurate.

How to deal reasonably with properties that work "better" than described in the help.
Do we have to assume that this property will disappear without notice?
-- Probably yes.
So what are the alternatives?

Two topics that keep catching my eye:

Code: Select all

hwnd = OpenWindow(#Window_0, <all other parameter>) 
; compiler -> correct window handle 
; Help -> nonzero ... can sometime just be #True 
; use instead 
if OpenWindow(#Window_0, <all other parameter>) 
  hwnd = WindowID(#Window_0) 

iDC = StartDrawing(<Something>) 
; compiler -> correct device context 
; Help -> nonzero ... can sometime just be #True 
; use instead 
; my educated guess 
dc = CreateDC_("DISPLAY", 0, 0, 0) 
hdc = CreateCompatibleDC_(dc) 
SelectObject_(hdc, <hImage>) 

[mk-soft]

Write a compiler warning when the PB version changes.

Code: Select all

;-TOP
CompilerIf #PB_Compiler_Version > 573
  CompilerWarning "Check:  StartDrawing result! (hDC)"
CompilerEndIf

[netmaestro]

Results of StartDrawing and OpenWindow haven't changed in 20 years and have survived several rewrites from the ground up. I wouldn't worry about them changing.

[Axolotl]

yes, that will probably be the case.
Therefore, a small one-line note in the help would not hurt.

Remark(s): On Windows the result value is a handle to the control/object/etc. in case of success.

Honestly written, however, there are some functions - almost all createXxxx functions - for which this behavior applies. And I don't know how this looks outside of windows?
Well, I just wanted to draw attention to it.