[Archived, Locked] Suggestions on documentation improvements
Re: Suggestions on documentation improvements
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).
Re: Suggestions on documentation improvements
Picture (or Pic):
... if the W and/or H options are not specified.
Edit: ...if neither the width nor the height are specified.
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.
Edit: ...if neither the width nor the height are specified.
Re: Suggestions on documentation improvements
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 := {}
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:
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
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
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"
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"
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
am i correctly assuming that numeric:=[] and assoc:={} would be the recommended initializations for making scripts forwardly compatible with AHK 2.x ?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.
Re: Suggestions on documentation improvements
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.lucianoc wrote:missing syntax for creating empty array?
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.
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.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.
Yes.am i correctly assuming that numeric:=[] and assoc:={} would be the recommended initializations for making scripts forwardly compatible with AHK 2.x ?
Re: Suggestions on documentation improvements
+1lexikos 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.
Re: Suggestions on documentation improvements
small mistake on Changes & New_Features page
[AHK] v2.0.5 | [WIN] 11 Pro (Version 22H2) | [GitHub] Profile
Re: Suggestions on documentation improvements
jNizM, you are about an hour too late.
Make Differentiation more obvious between using a word literally or as an example
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
Another example: Array
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
Code: Select all
Array := [Item1, Item2, ..., ItemN]
Array := Array(Item1, Item2, ..., ItemN)
Code: Select all
MyArray := [MyItem1, MyItem2, ..., MyItemN]
MyArray := Array(MyItem1, MyItem2, ..., MyItemN)
Re: Suggestions on documentation improvements
+1
but the docs are on github, you can easily edit them and create a pull request yourself right from the web interface
but the docs are on github, you can easily edit them and create a pull request yourself right from the web interface
Re: Suggestions on documentation improvements
Ok, I edited the chapter "Objects" and did a pull request (my first one ...).guest3456 wrote:but the docs are on github, you can easily edit them and create a pull request yourself right from the web interface
I will check later on if maybe there are subchapters, which are also affected.
Re: Suggestions on documentation improvements
are you sure?T-Rock wrote:Ok, I edited the chapter "Objects" and did a pull request (my first one ...).guest3456 wrote:but the docs are on github, you can easily edit them and create a pull request yourself right from the web interface
I will check later on if maybe there are subchapters, which are also affected.
i dont see your pull request
https://github.com/Lexikos/AutoHotkey_L-Docs/pulls
Re: Suggestions on documentation improvements
... obviously something went wrong, the pull request is in my profile ... however, I tried it again and now it's there
Re: Suggestions on documentation improvements
you changed more than you originally said. i don't agree with naming everything 'MyObject' to replace stuff like 'baseObj' or 'thing'
Re: Suggestions on documentation improvements
Well, you are right, I did more than I originally suggested, because I thought it makes sense to standardize the examples.guest3456 wrote:you changed more than you originally said. i don't agree with naming everything 'MyObject' to replace stuff like 'baseObj' or 'thing'
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?
Re: Suggestions on documentation improvements
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
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
Re: Suggestions on documentation improvements
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)
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)
Re: Suggestions on documentation improvements
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.
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.
Re: Suggestions on documentation improvements
I guess, I should be more precise about the reasons for my changes: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...
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.
The first time I saw this example, I wasn't sure if "base" might be an necessary prefix for base objects...lexikos wrote:The section of documentation is talking about "base objects". Clearly "baseObject" is more descriptive than "MyObject".
This example is introduced with "Base objects are ordinary objects", so for example like "my" own object.
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.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.
Re: Suggestions on documentation improvements
this is what i thought your original proposal was, and thought it was a good one.T-Rock wrote: 1) At first it should make the difference between a AutoHotkey key word
maybe "myBaseObj" thenT-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.
yep, thats always best. small commits allow specific changes to be cherry pickedT-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.
Return to “Suggestions on Documentation Improvements”
Who is online
Users browsing this forum: No registered users and 4 guests