[Archived, Locked] Suggestions on documentation improvements

Share your ideas as to how the documentation can be improved.
User avatar
jeeswg
Posts: 6902
Joined: 19 Dec 2016, 01:58
Location: UK

Re: Suggestions on documentation improvements

29 Sep 2019, 13:17

CONTROLSETCHECKED (CONTROL CHECK/UNCHECK) FOCUSES CONTROLS
- Re.:
check/uncheck Button controls (BM_SETCHECK v. BM_CLICK) - AutoHotkey Community
https://autohotkey.com/boards/viewtopic.php?f=5&t=68413
- The AHK v1/v2 documentation should mention that ControlSetChecked has the side effect of *focusing* the control.
- That BM_SETCHECK does not have this side effect, could be mentioned.

CONTROLFINDITEM (CONTROLGET FINDSTRING) AND CONTROLCHOOSESTRING
- ControlFindItem (matches whole).
- ControlChooseString (matches the start).
- The AHK v2 ControlFindItem page mentions ControlChooseString.
- The AHK v2 ControlChooseString page could/should mention ControlFindItem.
- The AHK v1 ControlGet FindString section could/should mention Control ChooseString.
- The AHK v1 Control ChooseString section could/should mention ControlGet FindString.

ENVSUB
- This is unclear:
Sets a variable to itself minus the given value (can also compare date-time values).
- EnvSub can be used to: get the difference between 2 datestamps in seconds/minutes/hours/days.

CODE EXAMPLES
- %0% versus A_Args: Some parts of the documentation still use %0% rather than A_Args.
- The MessageBox example on the DllCall page uses "0" rather than 0.

FUNCTION LISTS: LONG PATHS
- I've updated these lists (do notify of any issues):
list of every command/function/variable from across all versions - AutoHotkey Community
https://autohotkey.com/boards/viewtopic.php?f=74&t=27321&p=131642#p131642
list of every object type/property/method - AutoHotkey Community
https://autohotkey.com/boards/viewtopic.php?f=37&t=44081

- Functions that *do* support long paths (and Loop Files) could be mentioned explicitly, here:
Long Paths | AutoHotkey
https://www.autohotkey.com/docs/misc/LongPaths.htm

Code: Select all

- Functions etc that use paths in some way:
- Candidates (attempt at a full list):
DirXXX
DllCall
Download(/UrlDownloadToFile)
DriveXXX
EnvXXX
FileXXX
GuiCreate(/Gui-Add-Picture/GuiControl/SB_SetIcon)
IL_Add
ImageSearch
IniXXX
LoadPicture
ProcessXXX
RunXXX
SetWorkingDir
SoundPlay
SplashImage
SplitPath
TraySetIcon(/Menu-Tray-Icon/Menu-XXX-Icon)
WinGetProcessName
WinGetProcessPath
(Did I miss one?)
- Also:
#Include/#IncludeAgain
A_ variables
AHK main window title
Clipboard variable
ListLines main window text
Loop Files
FUNCTION LISTS: CASE/DEFAULT
- For my 'list of every...' list, and the control flow link below, please inform whether Case and Default are considered as control flow statements (or if not, what category of thing they are).
- Switch is listed here:
Scripting Language | AutoHotkey
https://www.autohotkey.com/docs/Language.htm#control-flow
- (Other terminology queries that the documentation could/should cover:)
terminology: objects/classes: keywords - AutoHotkey Community
https://autohotkey.com/boards/viewtopic.php?f=5&t=66547
terminology: statement separator, statement terminator - AutoHotkey Community
https://autohotkey.com/boards/viewtopic.php?f=5&t=66327

- Thanks.
homepage | tutorials | wish list | fun threads | donate
WARNING: copy your posts/messages before hitting Submit as you may lose them due to CAPTCHA
User avatar
lmstearn
Posts: 688
Joined: 11 Aug 2016, 02:32
Contact:

Re: Suggestions on documentation improvements

03 Oct 2019, 05:09

In DLLCall consider the following snippet under Ptr:
[v1.0.90+]: A pointer-sized integer, equivalent to Int or Int64 depending on whether the exe running the script is 32-bit or 64-bit. Ptr should be used for pointers to arrays or structures (such as RECT* or LPPOINT) and almost all handles (such as HWND, HBRUSH or HBITMAP).
If the parameter is a pointer to a single numeric value such as LPDWORD or int*, generally the * or P suffix should be used instead of "Ptr".

Ptr can also be used with the * or P suffix; it should be used with functions that output a pointer via LPVOID* or similar.
A rewording along the lines of the following might elucidate a little more:
[v1.0.90+]: A pointer-sized integer, equivalent to Int or Int64 depending on whether the exe running the script is 32-bit or 64-bit. Ptr should be used for pointers to arrays or structures (such as RECT* or LPPOINT) and almost all handles (such as HWND, HBRUSH or HBITMAP).

In the case of a pointer-to-pointer or double pointer, Ptr should be appended the "*" or P suffix when the parameter points to a single numeric value such as LPDWORD or int*, or in functions that output a pointer via LPVOID* or similar.
Also with the last comment in this thread regarding double pointers
lexikos wrote:
13 Aug 2014, 01:40
DllCall wrote:
For example, the following call would pass the contents of MyVar to MyFunction by address, but would also update MyVar to reflect any changes made to it by MyFunction: DllCall("MyDll\MyFunction", "Int*", MyVar).
This is a bit misleading; the contents (value) of MyVar is copied into a temporary variable of the appropriate type, and the address of this temporary variable (which is, by extension, the address of the value that MyVar contained) is passed.
A rewording of the snippet from the next section might go something like:
In the following call, for example, the contents (value) of MyVar are copied into a temporary variable
of the appropriate type- in this case int-, and the address of this temporary variable (which is, by extension,
the address of the value that MyVar contained) is passed to MyFunction:

Code: Select all

DllCall("MyDll\MyFunction", "Int*", MyVar)
:arrow: itros "ylbbub eht tuO kaerB" a ni kcuts m'I pleH
joefiesta
Posts: 494
Joined: 24 Jan 2016, 13:54
Location: Pa., USA

Re: Suggestions on documentation improvements

03 Oct 2019, 10:23

Awesome. I agree entirely with IMSTEARN. His rewordings are beyond admirable.

(He is using dashes incorrectly in case 2. It should read "... of the appropriate type (in this case int), and the address ...".) For one, he has removed the DISGUSTING word "GENERALLY (example 1). Documentaton shoud not speak in terms of generalities unless they are qualified (in which case they are no longer generalities).
lexikos
Posts: 9552
Joined: 30 Sep 2013, 04:07
Contact:

Re: Suggestions on documentation improvements

03 Oct 2019, 17:02

lmstearn wrote:In the case of a pointer-to-pointer or double pointer, Ptr should be appended the "*" or P suffix when the parameter points to a single numeric value such as LPDWORD or int*, or in functions that output a pointer via LPVOID* or similar.
This is clearly not correct. "when the parameter points to a single numeric value" is not a pointer-to-pointer and should not use Ptr* or PtrP. I'd suggest you leave the "pointer to a single numeric value" phrase as a separate point since you're apparently only trying to clarify Ptr*. I would also suggest not using the phrasing "Ptr should be appended the "*" or P suffix", which sounds very unnatural. You can say "use Ptr* or PtrP".
User avatar
lmstearn
Posts: 688
Joined: 11 Aug 2016, 02:32
Contact:

Re: Suggestions on documentation improvements

04 Oct 2019, 00:11

It's an absolutely awesome misread of said, so thanks for the heads up. The int* in context looked a bit awkward. If the AHK constructs like e.g. int* or Uint* are all marked up in inline code (see below), and the int* in "LPDWORD or int*" is not, it helps a bit. but it still might not work for everyone, I fear.
If the parameter is a pointer to a single numeric value such as LPDWORD or int*, generally the * or P suffix should be used instead of "Ptr".
Edit: Int* is not a Windows data type, so the following is preferred:
If the parameter is a pointer to a single numeric value such as LPDWORD or LPINT, generally the * or P suffix should be used instead of "Ptr".
Does this lose any of the above meaning?
If the parameter is typed as a pointer to a single numeric value like LPINT or LPDWORD, use, for example, int* or UintP, as the * or P suffix better fit the function signature than Ptr does.
The following line might be replaced
Ptr can also be used with the * or P suffix; it should be used with functions that output a pointer via LPVOID* or similar.
with something like:
In the case of a pointer-to-pointer or double pointer, as it applies to functions that output a pointer via LPVOID* or similar, "*" or P should be appended to Ptr as in Ptr* or PtrP.
Or as you say, this might be better:
In the case of a pointer-to-pointer or double pointer, as it applies to functions that output a pointer via LPVOID* or similar, Ptr should now be changed to Ptr* or PtrP.
@joefiesta: Does any of this come across as a bit long winded, generally speaking? :D
Last edited by lmstearn on 05 Oct 2019, 00:01, edited 2 times in total.
:arrow: itros "ylbbub eht tuO kaerB" a ni kcuts m'I pleH
joefiesta
Posts: 494
Joined: 24 Jan 2016, 13:54
Location: Pa., USA

Re: Suggestions on documentation improvements

04 Oct 2019, 10:05

@Imstearn - Speaking of long winded: I generally find that one of the biggest problems with the documentation is its extreme terseness. While I usually find that all the information you need is there, it is often extremely difficult to put all the pieces together to get the whole picture. Many of the concepts are EXTREMELY difficult to explain and would benefit greatly from more in depth explanations. Only when information is redundant is it long-winded.
User avatar
lmstearn
Posts: 688
Joined: 11 Aug 2016, 02:32
Contact:

Re: Suggestions on documentation improvements

11 Oct 2019, 00:49

If(Expression) wrote: If more than one statement is specified to be executed, those statements must be enclosed in braces (to create a block)
Variables and Expressions wrote: Commas may be used to write multiple sub-expressions on a single line. This is most commonly used to group together multiple assignments or function calls. For example: x:=1, y+=2, ++index, MyFunc().
Things like:

Code: Select all

If(Expression)
x:=1, y+=2, ++index, MyFunc()
can be handy as well. Should it be mentioned in If(Expression) thus:
If more than one line of statements are specified for execution, those lines must be enclosed in braces (to create a block)
There's more to add in the help to explain it, but it might not be a coding style our doc maintainers wish to promote. Thoughts?

Edit: Actually, it's not so straight-forward:

Code: Select all

If(1)
Loop, 2
If(1)
x:=1, y+=2, ++index, MyFunc()
Try this?
If more than one line of statements are specified for execution, those lines must be enclosed in braces (to create a block).
However, In the case of a conditional expression followed by other conditional expressions, apply the above rule to the last conditional expression in the list.
In continuing on our rocky journey, if an unbraced list of conditional expressions contains more than one if, the inclusion of an else at the end of the list will refer to no other than the last, (or nearest) if. Thus braces are necessary if the else was intended for some other if in the list.
:arrow: itros "ylbbub eht tuO kaerB" a ni kcuts m'I pleH
joefiesta
Posts: 494
Joined: 24 Jan 2016, 13:54
Location: Pa., USA

Re: Suggestions on documentation improvements

15 Oct 2019, 10:00

@Imstearn

I would clean it up just a little and fix the grammatical error. There is no reason to define block here.
If more than one line of statements IS specified for execution, those lines must be enclosed in a block. However, In the case of a conditional expression followed by other conditional expressions, apply the above rule to the last conditional expression in the list.
Also, I am not clear on what a "conditional expression" is. This phrase is not used in the AHK doc ANYWHERE. (That is, I don't particularly like the 2nd sentence but can't say how to improve it.)
joefiesta
Posts: 494
Joined: 24 Jan 2016, 13:54
Location: Pa., USA

Finding Older AHK versions

15 Oct 2019, 10:56

From the AHK Home page, www.autohotkey.com, one clicks DOWNLOADS. There one is presented 4 options:

- Download Current Version
- Download V2
- Download V1.0 deprecated
- Other versions

I find this misleading. And, that is why I could not find the "older" releases' downloads. The CURRENT version is version 1 (as made CLEAR by the fact that there is a Version 2). But, "Other versions" are all ALSO version 1. I think this page would be much clearer if the wording for these 4 choices were as follows:

- Download Current Version, current release
- Download V2
- Download V1.0 deprecated
- Download Current Version, older releases

But this is still not good enough. The issue is further complicated by the fact that the "Other vesions" link includes not only other releases but DOCUMENTATION downloads and links to GITHUB downloads, as well as UNINSTALLATION instructions.
Top

note: this was started as an ask for help issue, found here: https://www.autohotkey.com/boards/viewtopic.php?f=76&t=68655&p=295561#p295561
guest3456
Posts: 3454
Joined: 09 Oct 2013, 10:31

Re: Finding Older AHK versions

15 Oct 2019, 12:49

joefiesta wrote:
15 Oct 2019, 10:56
From the AHK Home page, www.autohotkey.com, one clicks DOWNLOADS. There one is presented 4 options:

- Download Current Version
- Download V2
- Download V1.0 deprecated
- Other versions

I find this misleading. And, that is why I could not find the "older" releases' downloads. The CURRENT version is version 1 (as made CLEAR by the fact that there is a Version 2). But, "Other versions" are all ALSO version 1. I think this page would be much clearer if the wording for these 4 choices were as follows:

- Download Current Version, current release
- Download V2
- Download V1.0 deprecated
- Download Current Version, older releases

But this is still not good enough. The issue is further complicated by the fact that the "Other vesions" link includes not only other releases but DOCUMENTATION downloads and links to GITHUB downloads, as well as UNINSTALLATION instructions.
Top

note: this was started as an ask for help issue, found here: https://www.autohotkey.com/boards/viewtopic.php?f=76&t=68655&p=295561#p295561
+10000

v2 shouldn't even be listed there yet

there should only be 2 choices:
- Download LATEST Version
- Other versions

Those should both be big buttons as we have currently. "Other versions" shouldn't be a small text link

is the homepage on github?

swagfag
Posts: 6222
Joined: 11 Jan 2017, 17:59

Re: Suggestions on documentation improvements

15 Oct 2019, 14:22

tbh id rehaul this page altogether
Spoiler
joefiesta
Posts: 494
Joined: 24 Jan 2016, 13:54
Location: Pa., USA

Filedelete and recycle bin

18 Oct 2019, 15:43

I think FILEDELETE doc should have a note indicating that files, if the volume on which they are found has a recylce bin ENABLED, are not sent to the recycle bin.

This leads me to ask, if a volume's recycle bin is NOT ENABLED (that is, it's recycle location is marked "Don't move files to the recycle bin. Remove files immediately when deleted." what happens if one issues a FILERECYCLE for a file on said volume? (I ask this here because it is not documented.)
iPhilip
Posts: 796
Joined: 02 Oct 2013, 12:21

Re: Filedelete and recycle bin

18 Oct 2019, 16:22

joefiesta wrote:
18 Oct 2019, 15:43
I think FILEDELETE doc should have a note indicating that files, if the volume on which they are found has a recylce bin ENABLED, are not sent to the recycle bin.

This leads me to ask, if a volume's recycle bin is NOT ENABLED (that is, it's recycle location is marked "Don't move files to the recycle bin. Remove files immediately when deleted." what happens if one issues a FILERECYCLE for a file on said volume? (I ask this here because it is not documented.)
Hi @joefiesta,

I just tried that as I was curious as well. If the recycle bin is not enabled, a FileRecycle command will permanently delete the file with an ErrorLevel value of 0.
Windows 10 Pro (64 bit) - AutoHotkey v2.0+ (Unicode 64-bit)
User avatar
kczx3
Posts: 1640
Joined: 06 Oct 2015, 21:39

Re: Suggestions on documentation improvements

18 Oct 2019, 19:11

Wow I never knew about FileRecycle. Glad I looked here!
daywalker
Posts: 32
Joined: 18 Jun 2019, 01:37

FileEncoding

22 Oct 2019, 02:57

Scripts - Definition & Usage | AutoHotkey
https://www.autohotkey.com/docs/Scripts.htm#auto
“Every thread launched by a hotkey, hotstring, menu item, GUI event, or timer starts off fresh with the default values for the following attributes as set in the auto-execute section. If unset, the standard defaults will apply (as documented on each of the following pages): "
Add to this list FileEncoding as it is reseted by a new thread.
User avatar
lmstearn
Posts: 688
Joined: 11 Aug 2016, 02:32
Contact:

Re: Suggestions on documentation improvements

23 Oct 2019, 23:54

joefiesta wrote:
15 Oct 2019, 10:00
There is no reason to define block here.
Defining block? Wasn't my intention. How about this?
If more than one line of statements IS specified for execution after the condition
We might reduce conditional expression to condition, but it doesn't change things much.
:arrow: itros "ylbbub eht tuO kaerB" a ni kcuts m'I pleH
iPhilip
Posts: 796
Joined: 02 Oct 2013, 12:21

Re: Filedelete and recycle bin

25 Oct 2019, 14:00

iPhilip wrote:
18 Oct 2019, 16:22
joefiesta wrote:
18 Oct 2019, 15:43
I think FILEDELETE doc should have a note indicating that files, if the volume on which they are found has a recylce bin ENABLED, are not sent to the recycle bin.

This leads me to ask, if a volume's recycle bin is NOT ENABLED (that is, it's recycle location is marked "Don't move files to the recycle bin. Remove files immediately when deleted." what happens if one issues a FILERECYCLE for a file on said volume? (I ask this here because it is not documented.)
Hi @joefiesta,

I just tried that as I was curious as well. If the recycle bin is not enabled, a FileRecycle command will permanently delete the file with an ErrorLevel value of 0.
I posted a suggestion for fixing this here.
Windows 10 Pro (64 bit) - AutoHotkey v2.0+ (Unicode 64-bit)
guest3456
Posts: 3454
Joined: 09 Oct 2013, 10:31

Re: Suggestions on documentation improvements

25 Oct 2019, 20:24

suggestion:

elaborate on the Pairs option for IniWrite and add an Example

i'm not clear if its just supposed to be a newline separated string with key=values on each line

AHK_user
Posts: 515
Joined: 04 Dec 2015, 14:52
Location: Belgium

Re: Suggestions on documentation improvements

26 Oct 2019, 06:39

Suggestion:
Add the following example in the Menu Syntax, to show how to access a function with parameters:
This makes the menu a lot more flexible.

Code: Select all

; Bind parameters to the function and returns a BoundFunc object.
BoundGivePar := Func("GivePar").Bind("First", "Test one")
BoundGivePar2 := Func("GivePar").Bind("Second", "Test two")

; Create the menu and show it
Menu MyMenu, Add, Give parameters, % BoundGivePar
Menu MyMenu, Add, Give parameters2, % BoundGivePar2
Menu MyMenu, Show

; Definition of custom function GivePar
GivePar(a, b, ItemName, MenuName, ItemPos) {
	MsgBox, a:`t`t%a%`nb:`t`t%b%`nItemName:`t%ItemName%`nMenuName:`t%MenuName%`nItemPos:`t`t%ItemPos%
}
User avatar
jeeswg
Posts: 6902
Joined: 19 Dec 2016, 01:58
Location: UK

Re: Suggestions on documentation improvements

26 Oct 2019, 06:55

AHK V2 FUNCTION INDEX
- Add Map.

FILESELECTFILE/FILESELECT (AHK V1 AND AHK V2)
- The 'Prompt' parameter should be 'Title'.
- (More correct/intuitive, matches MsgBox/InputBox.)

#SINGLEINSTANCE
- 'Prompt' is listed in AHK v2.
- 'Prompt' could/should be listed in AHK v1.
- (In AHK v1, '#SingleInstance prompt' works, although it is not explicitly defined in the source code, see SINGLE_INSTANCE_PROMPT.) [EDIT: AFAICS anything other than Force/Ignore/Off results in Prompt.]

FILE.POS
- The AHK v1 help states: 'File.Pos := Distance' and mentions 'Distance to move'.
- The AHK v2 help states: 'File.Pos := NewPos'.
- The AHK v2 help is far clearer. IMO it would be better to essentially copy the AHK v2 Pos/Seek descriptions (to the AHK v1 help).
- (Note: AHK v1 has File.Position, while AHK v2 doesn't.)

- Thanks.
Last edited by jeeswg on 29 Oct 2019, 05:57, edited 1 time in total.
homepage | tutorials | wish list | fun threads | donate
WARNING: copy your posts/messages before hitting Submit as you may lose them due to CAPTCHA

Return to “Suggestions on Documentation Improvements”

Who is online

Users browsing this forum: No registered users and 9 guests