Help File/Documentation Issues. (Discussion Only)

[jpm]

  On 8/23/2013 at 2:52 PM, Jon said:

We evaluate true to 1 and false to 0 internally, so that should be fine.

in fact bool correspond ti BOOL type in Windows API and it is defined as an Integer . Thanks MS ...

[czardas]

  On 8/23/2013 at 11:30 PM, mlipok said:

So why am I writing about:

in this documentation is a difference, information on the need for FileConstants.au3 is not included in Section REMARKS but in the PARAMETERS.

 

I agree with you - it is inconsistant. I would be inclined to add information about the required includes for optional parameters within the parameters section itself, rather than within the additional remarks.

Edited August 24, 2013 by czardas

[guinness]

FireFox,

I fixed the GUICtrlUpdatea and reverted the WinList commit because AZJIO's code (which I based my TidyText script on) created that output and not the one he reported.

[Jon]

  On 8/24/2013 at 7:10 AM, jpm said:

in fact bool correspond ti BOOL type in Windows API and it is defined as an Integer . Thanks MS ...

 

The WinAPI is designed for C. C doesn't have a bool

[FireFox]

  On 8/24/2013 at 8:28 AM, guinness said:

I fixed the GUICtrlUpdatea

ahhh I see now

  On 8/24/2013 at 8:28 AM, guinness said:

and reverted the WinList commit because AZJIO's code (which I based my TidyText script on) created that output and not the one he reported.

I couldn't run the check helpfile on the computer I was during the commit.

Thank you.

[guinness]

  On 8/24/2013 at 8:55 AM, FireFox said:

I couldn't run the check helpfile on the computer I was during the commit.

My script isn't that. I still have to fix a few things and then commit.

[FireFox]

  On 8/24/2013 at 9:01 AM, guinness said:

My script isn't that. I still have to fix a few things and then commit.

Well, I don't know by heart the syntax of the function parameters (I mean the damn spaces). Edited August 24, 2013 by FireFox

[guinness]

Neither did I at one point when I started out.

[mLipok]

  On 8/24/2013 at 7:29 AM, czardas said:

I agree with you - it is inconsistant. I would be inclined to add information about the required includes for optional parameters within the parameters section itself, rather than within the additional remarks.

If anyone else agree with me, then I call this as TRACK TICKET

[guinness]

If you mean something like ...

#include <StringConstants.au3>
StringInStr(...

then no it's not a good idea. The include is named above the UDFs only, as this is the file where the function can be found. Constants are a different subject altogether.

[mLipok]

  On 8/24/2013 at 10:57 AM, guinness said:

If you mean something like ...

#include <StringConstants.au3>
StringInStr(...

then no it's not a good idea. The include is named above the UDFs only, as this is the file where the function can be found. Constants are a different subject altogether.

 

You misunderstand me.

I would like her to be selected one correct option on how the description of the relevant file, which contains the definition of constants:

the first option (for example, a StringInStr)

parameter description: "Constants are defined in Constants.au3"

and

in Remarks: "The use of the values ​​specified above you must # include <StringConstants.au3> in your script."

the second option (for example, a DirCopy)

parameter description: "Constants are defined in FileConstants.au3"

and

in Remarks: no additional information

there is also a third option but I have not noticed in the present documentation:

in the description of the parameters: no additional information

and

in Remarks: Contains additional information

---

And by the way, I noticed that the documentation StringInStr

parameter description: "Constants are defined in Constants.au3"

and

in Remarks: "The use of the values ​​specified above you must # include <StringConstants.au3> in your script."

As you can see are indicated two different files - Is that correct?

EDIT: Track Ticket #2418

Edited August 24, 2013 by mlipok

[guinness]

I fixed the StringInStr issue with two different files.

OK, create a ticket for the other idea. Thanks.

[czardas]

Hmm StringInStr is tricky because the third parameter requires the includes for constants $STR_NOCASESENSE etc... but the remaining parameters do not. The StringInStr layout is the format I would use rather than the DirCopy format. Keeping stuff in the same place helps orientation.UDF functions are another story. I would add the includes to the syntax section in this case, which is where it appears already.

Edited August 24, 2013 by czardas

[mLipok]

Another thing to discuss
despite the fact issue with two different files

  On 8/24/2013 at 11:16 AM, mlipok said:

parameter description: "Constants are defined in Constants.au3"

and
in Remarks: "The use of the values ​​specified above you must # include <StringConstants.au3> in your script."
 

 

Regardless of where you placed the information,
I would like to choose the form.

I think that this form:
"The use of the values ​​specified above you must # include <StringConstants.au3> in your script."
is superior to that:
"Constants are defined in Constants.au3"

but the best would be the
"The use of the variables specified above you must # include <StringConstants.au3>. You can still use the Magic Number ( values listed in [] ) instead of the variables defined in this file."

because:

IMHO: Values mean Magic Number

IMHO: Variables not mean Magic Number

EDIT: and besides, a novice programmer needs to know that he has a choice, and how to use it.

EDIT:

amendment

"The use of the constants specified above you must # include <StringConstants.au3>. You can still use the Magic Number ( values listed in [] ) instead of the constants defined in this file."

because: these are constants, not variables

Edited August 24, 2013 by mlipok

[czardas]

The use of magic numbers is generally discouraged, but I am of the opinion the values should always be included in the documentation, which thankfully they are. The phrase 'Constants are defined in Constants.au3' doesn't really tell me very much. I'm getting confused because the help file that Azijo uploaded gives more or less the same format for these functions. I must have been looking at a different file.

[mLipok]

I noticed that in some documents, it is not a suitable substitute for the Magic Numbers.

Do you want to report this as TRACK TICKET?

[czardas]

  On 8/24/2013 at 11:56 AM, mlipok said:

I noticed that in some documents, it is not a suitable substitute for the Magic Numbers.

Do you want to report this as TRACK TICKET?

 

The helpfile is intended as a reference and not a course iin programming. There are plenty of topics where magic numbers are discussed on the forum. I actually like them, providing they are used in combination with BitOr, BitAnd etc... as opposed being to passed as a single integer when you need to combine them.

Edited August 24, 2013 by czardas

[Ascend4nt]

  On 8/23/2013 at 2:52 PM, Jon said:

We evaluate true to 1 and false to 0 internally, so that should be fine.

 

What I was getting at is - Is this something that can be documented?  And if so, can it be used for more than just DLLCall?  For example, that math equation I mentioned.. it currently still evaluates to 1 and 0 for booleans in testing, but its documented that the results of its use are unpredictable.

  On 8/24/2013 at 8:46 AM, Jon said:

The WinAPI is designed for C. C doesn't have a bool

 

C has had a boolean type since 1999, although it's spelled _Bool. Including <stdbool.h> allows one to use 'bool' instead though.  This is similar to how C11 uses underscores for types corresponding to C++11 types.  But if you've only used Microsoft compilers, you wouldn't know this - their compiler just barely supports the 1989 C standard.

[jpm]

  On 8/24/2013 at 12:13 PM, Ascend4nt said:

What I was getting at is - Is this something that can be documented?  And if so, can it be used for more than just DLLCall?  For example, that math equation I mentioned.. it currently still evaluates to 1 and 0 for booleans in testing, but its documented that the results of its use are unpredictable.

Unless I miss something DllCall is documented as much as possible with MSDN doc.

BOOL is described as MS does as Integer. The only thing you can argue is BOOL and bool is the same as the type is case insensitive.

[Ascend4nt]

  On 8/24/2013 at 12:40 PM, jpm said:

Unless I miss something DllCall is documented as much as possible with MSDN doc.

BOOL is described as MS does as Integer. The only thing you can argue is BOOL and bool is the same as the type is case insensitive.

jpm, you misunderstand my intention.  I'm discussing the True/False keywords in AutoIt, not so much the behavior of "bool" as a DLLCall type.  The case in fact is, as you said, that MS defines it as an integer.  Jon said True and False are evaluated internally as 1 and 0, so what I get from that is "bool" can be replaced with "int" in DLLCall with no ill effect.  However, I want to go a step further and find out if this behavior can be applied elsewhere. Or rather, it can currently be applied that way, but since its documented as undefined behavior, I'd like to see if that documentation can be changed (i.e. "True will evaluate to 1, False to 0").

I'm not quite sure what you are saying in regards to case sensitivity, as I've not mentioned that?  Windows BOOL is either TRUE (defined as 1 in the Windows SDK) or FALSE (0).  AutoIt currently follows this convention when translating True/False keywords.