[Archived, Locked] Suggestions on documentation improvements

Share your ideas as to how the documentation can be improved.
just me
Posts: 9426
Joined: 02 Oct 2013, 08:51
Location: Germany

Re: Suggestions on documentation improvements

08 Sep 2015, 05:18

The Standard Windows Fonts page contains outdated information and shoud be updated, removed, or replaced by an external link (I didn't find any useful).
just me
Posts: 9426
Joined: 02 Oct 2013, 08:51
Location: Germany

Re: Suggestions on documentation improvements

11 Sep 2015, 04:32

Picture (or Pic):
If the picture cannot be loaded or displayed (e.g. file not found), the control is left empty and its width and height are set to zero.
... if the W and/or H options are not specified.
Edit: ...if neither the width nor the height are specified.
User avatar
Lucianoc
Posts: 10
Joined: 02 Oct 2015, 01:21

Re: Suggestions on documentation improvements

11 Nov 2015, 00:30

http://autohotkey.com/docs/Objects.htm# ... ple_Arrays
http://autohotkey.com/docs/Objects.htm# ... ive_Arrays
Basic Usage and Syntax
> Object
> Associative_Arrays

missing syntax for creating empty array?
array := []
array := {}
Assign an item:
Array[Key] := Value

Also, in this section, or even if read from the top of the page, might lead one to assume that you can simply assign a value to a non-existing array.

Or in other words, perhaps it could mention that to use that syntax the array must have been created, even if empty by simply array:=[] or array:={}

Example:

Code: Select all

assoc_array["a"] := "alfa"
msgbox % assoc_array["a"]
For index, value in assoc_array
 msgbox % "Item " index " is '" value "'" "`r`n"
it gives no error but apparently does nothing either, 1 msgbox is empty and For is never looped

actually, its also true for numerical arrays

Code: Select all

assoc_array := {}
assoc_array["a"] := "alfa"
msgbox % assoc_array["a"]
For index, value in assoc_array
 msgbox % "Item " index " is '" value "'" "`r`n"
this workds just fine

my understanding of what's really happening might be lacking, but that small addition wouldn't hurt,

PHP (to name another script lang) allows such an approach to associative arrays, which might lead readers to wrongly assume what i did, specially since throughout the whole page the syntax :={} is given in examples for objects in general and not explicitly for arrays, and :=[{}] given in examples populates the [1] index

lastly, as noted at the end of the green header section
In AutoHotkey v1.x, simple arrays and associative arrays are the same thing. However, treating [] as a simple linear array helps to keep its role clear, and improves the chance of your script working with a future version of AutoHotkey, which might differentiate between simple arrays and associative arrays.
am i correctly assuming that numeric:=[] and assoc:={} would be the recommended initializations for making scripts forwardly compatible with AHK 2.x ?
lexikos
Posts: 9560
Joined: 30 Sep 2013, 04:07
Contact:

Re: Suggestions on documentation improvements

11 Nov 2015, 01:30

lucianoc wrote:missing syntax for creating empty array?
Did you think that Array := [Item1, Item2, ..., ItemN] was only about 3 or more items? Of course not. Just remove the items if you want an array with no items.

I hate adding length just to spell out the obvious, but I will consider your suggestion. I think the underlying problem is that there is no structured overview of the language, nor anything to teach the basic programming concepts required to tie everything together.
Also, in this section, or even if read from the top of the page, might lead one to assume that you can simply assign a value to a non-existing array.
Faulty thinking might lead one to assume many wrong things. The documentation shows syntax for utilizing an array. If the variable doesn't contain an array, the syntax shown is obviously not applicable. The very first step shown is creating an array.
am i correctly assuming that numeric:=[] and assoc:={} would be the recommended initializations for making scripts forwardly compatible with AHK 2.x ?
Yes.
guest3456
Posts: 3454
Joined: 09 Oct 2013, 10:31

Re: Suggestions on documentation improvements

11 Nov 2015, 01:56

lexikos wrote: I hate adding length just to spell out the obvious, but I will consider your suggestion. I think the underlying problem is that there is no structured overview of the language, nor anything to teach the basic programming concepts required to tie everything together.
+1

User avatar
jNizM
Posts: 3183
Joined: 30 Sep 2013, 01:33
Contact:

Re: Suggestions on documentation improvements

11 Nov 2015, 07:11

small mistake on Changes & New_Features page
Image
[AHK] v2.0.5 | [WIN] 11 Pro (Version 22H2) | [GitHub] Profile
T-Rock
Posts: 27
Joined: 01 Feb 2015, 09:11

Make Differentiation more obvious between using a word literally or as an example

20 Nov 2015, 03:57

I suggest to use the prefix "My" everywhere where a phrase is not supposed to be used literally and to declare this once in the help.

Especially in the chapter Objects this is often mixed.
For example the word "Func" is used in both ways a couple of times, which is very confusing to understand the content.
How about change this (and "fn") in MyFunc, MyFuncRef, MyFuncObj, ...?

For example: Func

Code: Select all

Func := Func("MyFunc")

A function can be called by reference using the following syntax:
RetVal := %Func%(Params)     ; Requires v1.1.07+
RetVal := Func.Call(Params)  ; Requires v1.1.19+
RetVal := Func.(Params)      ; Not recommended

Code: Select all

MyFuncRef := Func("MyFunc")

A function can be called by reference using the following syntax:
RetVal := %MyFuncRef%(Params)     ; Requires v1.1.07+
RetVal := MyFuncRef.Call(Params)  ; Requires v1.1.19+
RetVal := MyFuncRef.(Params)      ; Not recommended
Another example: Array

Code: Select all

Array := [Item1, Item2, ..., ItemN]
Array := Array(Item1, Item2, ..., ItemN)

Code: Select all

MyArray := [MyItem1, MyItem2, ..., MyItemN]
MyArray := Array(MyItem1, MyItem2, ..., MyItemN)
guest3456
Posts: 3454
Joined: 09 Oct 2013, 10:31

Re: Suggestions on documentation improvements

20 Nov 2015, 21:50

+1
but the docs are on github, you can easily edit them and create a pull request yourself right from the web interface

T-Rock
Posts: 27
Joined: 01 Feb 2015, 09:11

Re: Suggestions on documentation improvements

23 Nov 2015, 14:22

guest3456 wrote:but the docs are on github, you can easily edit them and create a pull request yourself right from the web interface
Ok, I edited the chapter "Objects" and did a pull request (my first one ...).
I will check later on if maybe there are subchapters, which are also affected.
guest3456
Posts: 3454
Joined: 09 Oct 2013, 10:31

Re: Suggestions on documentation improvements

23 Nov 2015, 17:01

T-Rock wrote:
guest3456 wrote:but the docs are on github, you can easily edit them and create a pull request yourself right from the web interface
Ok, I edited the chapter "Objects" and did a pull request (my first one ...).
I will check later on if maybe there are subchapters, which are also affected.
are you sure?

i dont see your pull request

https://github.com/Lexikos/AutoHotkey_L-Docs/pulls

T-Rock
Posts: 27
Joined: 01 Feb 2015, 09:11

Re: Suggestions on documentation improvements

23 Nov 2015, 17:23

... obviously something went wrong, the pull request is in my profile ... however, I tried it again and now it's there
guest3456
Posts: 3454
Joined: 09 Oct 2013, 10:31

Re: Suggestions on documentation improvements

23 Nov 2015, 17:39

you changed more than you originally said. i don't agree with naming everything 'MyObject' to replace stuff like 'baseObj' or 'thing'

T-Rock
Posts: 27
Joined: 01 Feb 2015, 09:11

Re: Suggestions on documentation improvements

23 Nov 2015, 18:49

guest3456 wrote:you changed more than you originally said. i don't agree with naming everything 'MyObject' to replace stuff like 'baseObj' or 'thing'
Well, you are right, I did more than I originally suggested, because I thought it makes sense to standardize the examples.

I made a suggestion and you made a hint, I should do the change myself.
So I spend some time and had my thoughts about every change I did and I think that every change made the examples more clear for beginners (like me).

As you don't like it, what do you suggest?
Where is the boundary for changes I am allowed to do?
Are my originally suggested changes also skipped?
guest3456
Posts: 3454
Joined: 09 Oct 2013, 10:31

Re: Suggestions on documentation improvements

24 Nov 2015, 16:52

well i mentioned the ones that i don't like, but thats just me personally

there are no boundaries, you can propose any changes you want, and submit a pull request

the maintainer (Lexikos in this case) will review the changes and decide whether or not he wants to accept them

T-Rock
Posts: 27
Joined: 01 Feb 2015, 09:11

Re: Suggestions on documentation improvements

24 Nov 2015, 17:58

Ok, fair enough, I thought you take the decision.

The example with „baseObject“ is introduced with „Base objects are just ordinary objects“.
I think „ MyObject“ can be more easily identified with an „ordinary object“ instead of using „baseObject“, which looks more like a Autohotkey key word.

Same with the other example you mentioned:
Second sentence of the introduction of prototypes speaks about how to construct an „ordinary object“.

By the way wouldn’t it make more sense to have this discussion in github with the pull request? (like the comment from joedf)
lexikos
Posts: 9560
Joined: 30 Sep 2013, 04:07
Contact:

Re: Suggestions on documentation improvements

24 Nov 2015, 18:44

So by your reasoning, it would make sense to name every variable that stores an object created by [] or {} or new classname "MyObject", regardless of its purpose. You can call every variable that contains a string "MyString" and so on...

The section of documentation is talking about "base objects". Clearly "baseObject" is more descriptive than "MyObject".

I have more to say about your other changes, which don't match the description of the pull request, but I will leave that for later.
T-Rock
Posts: 27
Joined: 01 Feb 2015, 09:11

Re: Suggestions on documentation improvements

25 Nov 2015, 09:29

lexikos wrote:So by your reasoning, it would make sense to name every variable that stores an object created by [] or {} or new classname "MyObject", regardless of its purpose. You can call every variable that contains a string "MyString" and so on...
I guess, I should be more precise about the reasons for my changes:

1) At first it should make the difference between a AutoHotkey key word (see "Command and Function Index") and an example name in the examples more obvious, especially with the AutoHotkey functions "Array()", "Object()" and "Func()", like:
Array := Array(Item1, Item2, ..., ItemN)
-> MyArray := Array(Item1, Item2, ..., ItemN)

It would make sense from my point of view to name
a variable that stores an object created by []: MyArray
a variable that stores an object created by {}: MyObject
a variable that stores an object created by new classname: MyObject
a variable that contains a string: String
"String" itself is not an AutoHotkey command or function, it is always used in combination with another word (StringCaseSense, StringGetPos, ...)
and so on ...

I would like to have it straightforward, but it also depends of course on the context:
Func := Func("MyFunc")
-> FuncRef := Func("MyFuncName")
In the sentence before "MyFunc" (as of my pull request) is used as a variable containing a function name, so for this example with using "MyFunc" in the brackets you would get a wrong impression and "MyFuncName" is more precise.

2) Standardizing the examples (reuse a common name like "MyObject")
For example in chapter "Objects" are a couple of different names for parameters: Parameters, Params, param, param1, param2, p1, p2, ...
or another example: Array, array, arr

3) Making it easy for beginners to reproduce each paragraph with the given example:
I say it's much easier to adept an example with "MyObject" (even more when it is repeated in all examples) instead of "thing" or "obj".
I am sure, that all of you writers knew about objects before, but I tried to learn it from the help and then the most examples are more confusing than helping.
lexikos wrote:The section of documentation is talking about "base objects". Clearly "baseObject" is more descriptive than "MyObject".
The first time I saw this example, I wasn't sure if "base" might be an necessary prefix for base objects...
This example is introduced with "Base objects are ordinary objects", so for example like "my" own object.
lexikos wrote:I have more to say about your other changes, which don't match the description of the pull request, but I will leave that for later.
I see now instead of creating one pull request with different kind of changes, i should have done single pull requests for each kind of change.
guest3456
Posts: 3454
Joined: 09 Oct 2013, 10:31

Re: Suggestions on documentation improvements

25 Nov 2015, 13:05

T-Rock wrote: 1) At first it should make the difference between a AutoHotkey key word
this is what i thought your original proposal was, and thought it was a good one.
T-Rock wrote: The first time I saw this example, I wasn't sure if "base" might be an necessary prefix for base objects...
This example is introduced with "Base objects are ordinary objects", so for example like "my" own object.
maybe "myBaseObj" then
T-Rock wrote: I see now instead of creating one pull request with different kind of changes, i should have done single pull requests for each kind of change.
yep, thats always best. small commits allow specific changes to be cherry picked


Return to “Suggestions on Documentation Improvements”

Who is online

Users browsing this forum: No registered users and 4 guests