[Archived, Locked] Suggestions on documentation improvements

Share your ideas as to how the documentation can be improved.
gregster
Posts: 8885
Joined: 30 Sep 2013, 06:48

Re: Suggestions on documentation improvements

14 Feb 2019, 19:37

joefiesta wrote:
14 Feb 2019, 17:38
The function call is NOT an expression. The Parameters are expressions, but not the call itself.
If functions calls wouldn't be expressions, functions wouldn't work at all in current Autohotkey (syntax); they wouldn't get evaluated..
Clearly, function calls are expressions itself (even when parameters, if present, get evaluated first as expressions). The point is that functions calls have a different syntax than variables (not really surprising, is it?).

Also
https://autohotkey.com/docs/Language.htm#expressions wrote:Expressions are combinations of one or more values, variables, operators and function calls.
(underline by me). The presence (or evaluation) of one or several variables don't prevent an over-arching expression (this is really not ahk-specific).
coffee
Posts: 133
Joined: 01 Apr 2017, 07:55

Re: Suggestions on documentation improvements

14 Feb 2019, 22:11

Seriously, what the fuck is going in this thread? People who have been using autohotkey for ages and still have no fucking clue about autohotkey's can-count-with-a-single-hand value types.
Let's ignore the absolute retardation that objects should be compared as strings and move over to:

joefiesta wrote:
14 Feb 2019, 11:23
Doc, at https://autohotkey.com/docs/Functions.htm#intro, states
Since a function call is an expression, any variable names in its parameter list should not be enclosed in percent signs.
this is not precise. The "function call" is not an expression. If it were, the following would work:

Code: Select all

in := "strlen"
a := in("asdf")
msgbox % a
exitapp
in := "strlen" This is a string literal. String literals are not functions. So they can't be called. String literals are never functions, anywhere, neither do they magically transform into a function just 'bcuz'.

Alternatively, %in%("asdf") Uses the value/contents of the variable in, which is a string, to find a function with that name and calls it.

If autohotkey had first class functions, you wouldn't do in := "StrLen" to grab the reference, since that is a string assignment, that causes the variable to hold a string; you would do in := StrLen, where StrLen would hold a function reference/pointer/direction-arrow-to-something-in-memory-that-can-be-called. But since they are not, StrLen is considered a plain variable, unless you manually:

Code: Select all

StrLen := Func("StrLen")
in := StrLen
Miscellaneous:

Code: Select all

in := Func("strlen")
in.call("adsf") ; Simply because autohotkey_l has the limitation of not being able to call function references without .call.
; if .call wasn't enforced, you would do
in("asdf")
joefiesta wrote:
14 Feb 2019, 11:23
The doc should read: The PARAMETERS in a function call are expressions.
https://github.com/Lexikos/AutoHotkey_L/blob/master/source/script.cpp#L2807
ParseAndAddLine(pending_buf, ACT_EXPRESSION)

https://github.com/Lexikos/AutoHotkey_L/blob/alpha/source/script.cpp#L4604
aActionType = ACT_EXPRESSION;
joefiesta wrote:
14 Feb 2019, 17:38
you guys don't get the point. My ONLY point is the semantics of the statement "Since a function call is an expression" The function call is NOT an expression. The Parameters are expressions, but not the call itself.
Function calls are considered expressions.

Function definitions are not expressions, unless it's =>.

Hopefully the thread can resume on being about documentation improvements and not ask for help or tutorials. Roll in for some light reading on "documentation improvements" and get trollbaited into this shit.
autohotkey.com/trollbaitboards

Yeah I know the "snowflake", "hurdurrr don't read it if you don't like it durrsss *spits*", well I'm running out of subforums at this point.
User avatar
nnnik
Posts: 4500
Joined: 30 Sep 2013, 01:01
Location: Germany

Re: Suggestions on documentation improvements

15 Feb 2019, 07:04

The name of the function call doesn't have to be an expression just when the entire function call is an expression - this and that is unrelated semantically.
Recommends AHK Studio
swagfag
Posts: 6222
Joined: 11 Jan 2017, 17:59

Re: Suggestions on documentation improvements

19 Feb 2019, 17:24

greyed out deprecated functions in sidebar
maybe also make deprecated stuff more
unsightly
User avatar
jeeswg
Posts: 6902
Joined: 19 Dec 2016, 01:58
Location: UK

Re: Suggestions on documentation improvements

03 Mar 2019, 19:38

The 49.7 day A_TickCount (GetTickCount) limitation could be mentioned.
A_TickCount to use GetTickCount64 instead of GetTickCount - AutoHotkey Community
https://autohotkey.com/boards/viewtopic.php?f=13&t=4667&p=26728#p26728
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: 681
Joined: 11 Aug 2016, 02:32
Contact:

Re: Suggestions on documentation improvements

24 Mar 2019, 01:15

As an enhancement, any commands on the main LH help treeview marked as deprecated (or for AutoIT scripts only) to have a different colour, or some other standout (e.g. strikethrough) attribute. Helpful for folks new to AHK who don't want too much of the history while browsing.
Thanks.
Edit: Exclusively for those who haven't checked 2 posts above. :P Sorry.
Last edited by lmstearn on 28 Apr 2019, 09:45, edited 1 time in total.
:arrow: itros "ylbbub eht tuO kaerB" a ni kcuts m'I pleH
User avatar
lmstearn
Posts: 681
Joined: 11 Aug 2016, 02:32
Contact:

Re: Suggestions on documentation improvements

09 Apr 2019, 01:34

Regarding the code for RunAs the param for restart is also /r
Does the code want something like this instead,

Code: Select all

if not RegExMatch(full_command_line, " /r(?!\S)"))
or is the existing help snippet sufficient?
Thanks
:arrow: itros "ylbbub eht tuO kaerB" a ni kcuts m'I pleH
User avatar
jeeswg
Posts: 6902
Joined: 19 Dec 2016, 01:58
Location: UK

Re: Suggestions on documentation improvements

13 Apr 2019, 05:40

RECAP
- 4 issues. From 2 pages ago.
Suggestions on documentation improvements - Page 26 - AutoHotkey Community
https://autohotkey.com/boards/viewtopic.php?f=13&t=1434&p=262959#p262959
- Confirmation re. the Float/Double standard.
Suggestions on documentation improvements - Page 25 - AutoHotkey Community
https://autohotkey.com/boards/viewtopic.php?f=13&t=1434&p=257406#p257406
- A note about A_TickCount, mentioned 3 posts up.

NEW ISSUES
- A note about the 127-char limit for SoundPlay:
soundplay filename length limit? - AutoHotkey Community
https://autohotkey.com/boards/viewtopic.php?f=5&t=63530&p=272450#p272450
- A note that NumGet/NumPut can both accept 'UInt64', although that this will be functionality equivalent to using Int64.
- A note about any FileXXX functions that don't create folders.
FileMove not working - FileDelete and FileAppend working normally - AutoHotkey Community
https://autohotkey.com/boards/viewtopic.php?f=5&t=63705
- 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
Ragnar
Posts: 608
Joined: 30 Sep 2013, 15:25

Re: Suggestions on documentation improvements

19 Apr 2019, 08:19

jeeswg wrote: - A note about the 127-char limit for SoundPlay:
soundplay filename length limit? - AutoHotkey Community
https://autohotkey.com/boards/viewtopic.php?f=5&t=63530&p=272450#p272450
Ragnar wrote:
19 Apr 2019, 06:43
After some testing, it turned out that apparently only the path names of WAV files are affected by this 127-character-limit. For example, MP3 files with a path name longer than 127 characters will work, but only up to a maximum of 255 characters.
Before I make any changes to the SendPlay site, perhaps someone else should check whether the above statement is actually true.
joefiesta
Posts: 494
Joined: 24 Jan 2016, 13:54
Location: Pa., USA

a_ScriptFullPath

29 Apr 2019, 08:28

Doc states:
A_ScriptDir The full path of the directory where the current script is located. The final backslash is omitted (even for root directories).

A_ScriptName The file name of the current script, without its path, e.g. MyScript.ahk.

A_ScriptFullPath The combination of the above two variables to give the complete file specification of the script, e.g. C:\My Documents\My Script.ahk
The explanation for A_ScriptFullPath is not exact. It should mention that the two variables are concatenated WITH A BACKSLASH added between them.
User avatar
lmstearn
Posts: 681
Joined: 11 Aug 2016, 02:32
Contact:

Re: Suggestions on documentation improvements

29 Apr 2019, 09:47

Regarding the code for the second example in Functor

Code: Select all

<Snip>
; Create an array of functions.
funcArray := new FuncArrayType
; Add some functions to the array (can be done at any point).
funcArray.Push(Func("One"))
funcArray.Push(Func("Two"))
; Create an object which uses the array as a method.
obj := {method: funcArray}
; Call the method.
obj.method("foo", "bar")<snip>
The line obj := {method: funcArray] obviously executes as described in the comment above it. The assignment itself looks similar in syntax to the associative array {key:value}, so to make it clear here that method is a reserved word, a highlight for it?
Thanks.
:arrow: itros "ylbbub eht tuO kaerB" a ni kcuts m'I pleH
Helgef
Posts: 4709
Joined: 17 Jul 2016, 01:02
Contact:

Re: Suggestions on documentation improvements

29 Apr 2019, 12:55

@joefiesta the variable wouldn't yield the complete file specification of the script if it returned something which was missing something, such aa a backslash.
Helgef
Posts: 4709
Joined: 17 Jul 2016, 01:02
Contact:

Re: Suggestions on documentation improvements

29 Apr 2019, 13:00

@lmstearn , The assignment itself looks similar in syntax to the associative array {key:value}, because that is exactly what it is. method is not a reserved word, you could name it banana and then call obj.banana().

Cheers.
User avatar
lmstearn
Posts: 681
Joined: 11 Aug 2016, 02:32
Contact:

Re: Suggestions on documentation improvements

29 Apr 2019, 23:58

Helgef wrote:
29 Apr 2019, 13:00
@lmstearn , The assignment itself looks similar in syntax to the associative array {key:value}, because that is exactly what it is. method is not a reserved word, you could name it banana and then call obj.banana().

Cheers.
Ah okay, was reading from Associative arrays that:
Keys can be strings, integers or objects, while values can be of any type
And, again, from Func:
; Create an object which uses the array as a method.
I inferred that method must then be some kind of object rather than a string or integer- if it isn't then it shouldn't matter much in any case.
: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

30 Apr 2019, 09:30

I think one of the best points of Imstearn's comment is this
The assignment itself looks similar in syntax to the associative array {key:value}, so to make it clear here that method is a reserved word, a highlight for it?
The AHKk documentation does not differentiate between RESERVED words, variable and parameters, etc. In most documentation--at least any of any quality--it is clear what is a reserved word and what is a subsitutable value. The fact of the matter is: AHK documenters don't want to GIVE UP USING MIXED CASE when it is only for the sake of appearance or readability. Most documentation would have RESERVED words in ALL CAPS and non-reserved words/parameters/etc in lower case. (There are, of course other methods of making this distinction. For example, many IBM mainframe languages allow truncation of commands to a certain minimal number of characters. In this case, they show, for example, SETTIMER as SETTimer (not a real command) which indicates the command may be abbreviated to as short as SETT. In this case, reserved words are treated differently, usually in BOLD fonts or ITALICIZED fonts.)
burque505
Posts: 1731
Joined: 22 Jan 2017, 19:37

Re: Suggestions on documentation improvements

06 May 2019, 08:09

Looking through release notes for past versions of 2.0 (here) I find:
Changes to ([{ continuation:

Fixed detection of missing close-quote in continuation expressions.
Fixed comment sections and line continuation in or following ([{ continuation.
Fixed ([{ continuation for hotkeys with same-line action.
Fixed ([{ continuation for #If.
I don't find any entries for "([{ continuation" except that link.

As dealing with large text passages of text containing reserved or unacceptable characters is quite a chore, and this seems like it *might* offer some help, I am hoping this feature is documented somewhere.
Thanks!
swagfag
Posts: 6222
Joined: 11 Jan 2017, 17:59

Re: Suggestions on documentation improvements

06 May 2019, 08:14

its right there above the continuation section article https://lexikos.github.io/v2/docs/Scripts.htm#continuation-expr
burque505
Posts: 1731
Joined: 22 Jan 2017, 19:37

Re: Suggestions on documentation improvements

06 May 2019, 09:38

@swagfag, thanks. It would have never occurred to me that "([{ continuation" meant "continuation with '(/[/{'" or "continuation with (, [ or {." I took ([{ to be a single delimiter, similar to {{ in jinja2, or ${ in Mako.
joefiesta
Posts: 494
Joined: 24 Jan 2016, 13:54
Location: Pa., USA

CRITICAL

16 May 2019, 09:25

command syntax for CRITICAL is shown as
Critical , Off
Critical 50 ; See bottom of remarks.
1. The ON parameter is not shown

2. I believe the numerical Message Check Interval value would be better shown as "n", or just some other variable name. why 50? that is arbitrary

3. The syntax says "See bottom of remarks". There IS NO REMARKS SECTION. This would be more correct if it stated "See Message Check Interval (below)." However, I must question why this PARAMETER's value is not defined expliticitly (and before going on and explaining the command).
User avatar
jeeswg
Posts: 6902
Joined: 19 Dec 2016, 01:58
Location: UK

Re: Suggestions on documentation improvements

31 May 2019, 23:39

The AHK v2 index is missing:
Float / Integer / String, StrCompare, BufferAlloc
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 11 guests