[Archived, Locked] Suggestions on documentation improvements

Share your ideas as to how the documentation can be improved.
User avatar
nnnik
Posts: 4500
Joined: 30 Sep 2013, 01:01
Location: Germany

Re: Suggestions on documentation improvements

16 Dec 2019, 03:32

Thats oddly unnecessary specific and potentially misleading because it may still be possible to get the ExitCode using the WinAPI.
Recommends AHK Studio
joefiesta
Posts: 494
Joined: 24 Jan 2016, 13:54
Location: Pa., USA

Re: Suggestions on documentation improvements

16 Dec 2019, 12:24

@nnnik I fail to see why being more specific is bad. RUN is an exception to the stated rule. Secondly, how could it ever be possible to get the Exitcode from a RUN command? The program invoked is very likely still running--indeed, could run for hours. Long after the next line of code in a scipt is executed.
swagfag
Posts: 6222
Joined: 11 Jan 2017, 17:59

Re: Suggestions on documentation improvements

16 Dec 2019, 17:30

if anything it should read
This code is accessible to any program that spawned the script, such as another script (via RunWait) or a batch (.bat) file, or can be retrieved with GetExitCodeProcess().
User avatar
nnnik
Posts: 4500
Joined: 30 Sep 2013, 01:01
Location: Germany

Re: Suggestions on documentation improvements

17 Dec 2019, 02:38

And what if we find more methods to get the ExitCode?
Would you add them all as list there?
To me adding to this inaccurate statement is only inaccuracy with extra steps.
Recommends AHK Studio
swagfag
Posts: 6222
Joined: 11 Jan 2017, 17:59

Re: Suggestions on documentation improvements

17 Dec 2019, 08:35

perhaps, perhaps not. it depends on their usefulness and how easy they are to implement. for instance, if another method did exist, but u had to ReadProcessMemory a long chain of pointers(that in and of itself requires a minitutorial) and it only worked on select processes on windows 10 buildXXXX 64bit, then no, obviously i wouldnt include it.
GetExitCodeProcess is the dedicated "windows way" of retrieving the status code and is what ahk(and others, python, go, etc) has used ever since its inception
so if u long for accurate statements, delete this entire sentence and replace it with:
This code can be retrieved with GetExitCodeProcess().
then again, this probably wont be of much use to ur average ahk user
User avatar
nnnik
Posts: 4500
Joined: 30 Sep 2013, 01:01
Location: Germany

Re: Suggestions on documentation improvements

17 Dec 2019, 08:56

No I wouldnt say that getExitCode is the dedicated windows way.
As background: ExitCodes are a numerical number that a process gives to its caller when it returns.
Its an ancient piece of technology steming from the era when command lines where more prevalent and execution was mostly linear.
The exit code was an additional status variable that told the system something about the operation that the process was doing.
For example it can be as simple as a inStr process returning 1 or 0 depending on whether the needle was found in the Haystack or not.
This return code was always given to the parent when execution finished.
Of course nowadays execution is not so linear anymore and a parent might do something after a child has started. Some method may have been implemented to get the childs exit code.
This method clearly isn't getProcessExitCode because that isnt limited to parents but rather part of the same library that allows the modification and reading of other processes memories.
It could be that there are many other easier ways that are viable and prefereable in this or other situations.

To me it just seems that you are trying to be overly specific with extra information that might relate to the topic but underestimate how complex the topic you actually try to talk about is.

To give a comparison: To me it feels like you suddenly talk about ways to acquire water when we just want to write a short paragraph about clouds.
Recommends AHK Studio
swagfag
Posts: 6222
Joined: 11 Jan 2017, 17:59

Re: Suggestions on documentation improvements

17 Dec 2019, 10:03

were talking about:
  • ExitApp
  • ExitApp's exit code
  • ExitApp's doc entry
we arent talking about:
  • unix processes
  • u deciding "IniWrite an exit code to a file when the child process exits and have the parent process monitor that file" is an easier, viable, preferable and more elegant method, implemented to get the childs exit code(frankly, im not entirely sure what u had in mind here, but feel free to elaborate, since ure so well versed in this incredibly complex topic and all)
  • clouds, lakes and water dowsing
what, then, is the dedicated windows way of retrieving the exit code? specifically, the one which exit() produces(since, u know..., thats what ExitApp ultimately depends on)

we can deal with this in one of several ways:
  1. leave it as is. inaccurate(if the program doesnt bother checking the exit code with GetExitCodeProcess or some other as-of-yet-undiscovered method, then the exit code wont be accessible) but who cares(well, up until now, apparently nobody did)
    This code is accessible to any program that spawned the script, such as another script (via RunWait) or a batch (.bat) file.
  2. why bother mentioning Run? it doesnt deal with exit codes
    This code is accessible to any program that spawned the script, such as another script (via RunWait) or a batch (.bat) file, with the exception of having been spawned by the Autohotkey RUN command.
  3. accurate, but technical and probably not very useful to most people
    This code can be retrieved with GetExitCodeProcess().
  4. what wrong with this again?
    This code is accessible to any program that spawned the script, such as another script (via RunWait) or a batch (.bat) file, or can be retrieved with GetExitCodeProcess().
  5. deleting the sentence entirely
  6. something else entirely
it really isnt that complex a topic
User avatar
nnnik
Posts: 4500
Joined: 30 Sep 2013, 01:01
Location: Germany

Re: Suggestions on documentation improvements

17 Dec 2019, 10:13

ExitApps doc entry is not about ways said exit codes can be retrieved but rather what they are good for.
They are mainly to relay information to the creator of the process.
So I would word it as:
ExitCodes are used to relay information to the creator of the Scripts process.
And remove the rest and the examples because people apparently read too much into it.
Recommends AHK Studio
swagfag
Posts: 6222
Joined: 11 Jan 2017, 17:59

Re: Suggestions on documentation improvements

17 Dec 2019, 16:17

i wasnt entirely opposed to deleting it altogether, though, this could work too, i suppose
iPhilip
Posts: 801
Joined: 02 Oct 2013, 12:21

Memory leak in ComObjQuery's documentation page

20 Dec 2019, 17:31

I would like to suggest a change to Example #1 on ComObjQuery's documentation page to address what I believe is a memory leak. To test the leak I used the following script and monitored the process' Private Bytes according to the "Using Performance Monitor to Find a User-Mode Memory Leak" note on Microsoft's Windows Degugging Tools page.

Code: Select all

#NoEnv

F3::
obj := ComObjCreate("Scripting.Dictionary")

IID_IProvideClassInfo := "{B196B283-BAB4-101A-B69C-00AA00341D07}"

; Request a pointer to the object's IProvideClassInfo interface.
if !(pci := ComObjQuery(obj, IID_IProvideClassInfo))
{
	MsgBox IProvideClassInfo interface not supported.
	return
}

Loop
{
	; Call GetClassInfo to retrieve a pointer to the ITypeInfo interface.
	DllCall(vtable(pci, 3), "ptr", pci, "ptr*", ti)

	; Call GetDocumentation to get the object's full type name.
	DllCall(vtable(ti, 12), "ptr", ti, "int", -1, "ptr*", name, "ptr", 0, "ptr", 0, "ptr", 0)
	
	; Convert the BSTR pointer to a usable string.
	name := StrGet(name, "UTF-16")

	; Release raw interface pointers.
	ObjRelease(ti)
}
ObjRelease(pci)

; Display the type name!
MsgBox % "Class name: " name

Esc::ExitApp

vtable(ptr, n) {
    ; NumGet(ptr+0) returns the address of the object's virtual function
    ; table (vtable for short). The remainder of the expression retrieves
    ; the address of the nth function's address from the vtable.
    return NumGet(NumGet(ptr+0), n*A_PtrSize)
}
The resulting graph is as follows:
Without SysFreeString.gif
Without SysFreeString.gif (17.98 KiB) Viewed 5546 times
The documentation on the ITypeInfo::GetDocumentation method recommends that SysFreeString be used to free the BSTR referenced by name. With that, the resulting graph shows no memory leak:
With SysFreeString.gif
With SysFreeString.gif (17.6 KiB) Viewed 5546 times
Thus, I would recommend the following version of the example:

Code: Select all

obj := ComObjCreate("Scripting.Dictionary")

MsgBox % "Interface name: " ComObjType(obj, "name")

IID_IProvideClassInfo := "{B196B283-BAB4-101A-B69C-00AA00341D07}"

; Request a pointer to the object's IProvideClassInfo interface.
if !(pci := ComObjQuery(obj, IID_IProvideClassInfo))
{
    MsgBox IProvideClassInfo interface not supported.
    return
}

; Call GetClassInfo to retrieve a pointer to the ITypeInfo interface.
DllCall(vtable(pci, 3), "ptr", pci, "ptr*", ti)

; Call GetDocumentation to get the object's full type name.
DllCall(vtable(ti, 12), "ptr", ti, "int", -1, "ptr*", pname, "ptr", 0, "ptr", 0, "ptr", 0)

; Convert the BSTR pointer to a usable string.
name := StrGet(pname, "UTF-16")

; Free the BSTR referenced by pname
DllCall("OleAut32\SysFreeString", "ptr", pname)

; Release raw interface pointers.
ObjRelease(ti)
ObjRelease(pci)

; Display the type name!
MsgBox % "Class name: " name

vtable(ptr, n) {
    ; NumGet(ptr+0) returns the address of the object's virtual function
    ; table (vtable for short). The remainder of the expression retrieves
    ; the address of the nth function's address from the vtable.
    return NumGet(NumGet(ptr+0), n*A_PtrSize)
}
Cheers!

- iPhilip
Windows 10 Pro (64 bit) - AutoHotkey v2.0+ (Unicode 64-bit)
swagfag
Posts: 6222
Joined: 11 Jan 2017, 17:59

Re: Suggestions on documentation improvements

20 Dec 2019, 18:23

yes, with bstrs the onus is usually on the caller to clean up. good catch
joefiesta
Posts: 494
Joined: 24 Jan 2016, 13:54
Location: Pa., USA

Re: Suggestions on documentation improvements

23 Dec 2019, 09:48

It's all very wonderful to make a doc suggestion. And even better when someone agrees the doc needs changing. Why, then, do we virtually NEVER read the reply: "Yes, and we (whoever we is) will change the documentation"?
joefiesta
Posts: 494
Joined: 24 Jan 2016, 13:54
Location: Pa., USA

Re: Suggestions on documentation improvements

23 Dec 2019, 09:54

I think Suggestions for documentation improvement should be it's own forum topic. Then, each suggestion would be a separate forum entry. And each could get marked: AGREED, DISAGREED or something. All the banter that goes on about some suggestions goes WAY BEYOND the simple point of making a suggestion.

Take for example the previous suggestion about the maximum length of a string input into an INPUT BOX. The author simply wanted the doc changed to say "the maximum allowed length..."
That's all. And, that is all that really needs to be done. ONE SENTENCE added. He wasn't concerned with changing the way INPUT works, and that should not have been a matter of discussionk in "Suggestions on documentation improvements". That should be in a wish list or bug forum.
User avatar
nnnik
Posts: 4500
Joined: 30 Sep 2013, 01:01
Location: Germany

Re: Suggestions on documentation improvements

23 Dec 2019, 10:57

I think this topic has grown beyond the initial outset.
A forum section might improve organisation of the topics.
Recommends AHK Studio
swagfag
Posts: 6222
Joined: 11 Jan 2017, 17:59

Re: Suggestions on documentation improvements

23 Dec 2019, 19:44

this thread is a dumping ground with no clear delineation of where one suggestion begins and ends. i dont know if anyone actually bothers implementing the suggestions(@Ragnar maybe or perhaps even @lexikos himself) but it must be a pain to sift through pages of unorganized drivel
this harkens back to the lack of clearly defined contribution guidelines. u want something fixed int he docs? cool, do u:
  • post here and bury ur OP in 2 pages of back and forth?
  • do u make a new thread in Wishlist?
  • do u raise a github issue?
  • do u straight up submit pull requests(theres an "edit on gh" button in the docs, after all), risking wasting ur time in case uve failed to fully comprehend the context of the change ure proposing?
same goes for language suggestions and bug reports

ultimately, @lexikos will be reviewing and merging those changes(unless he decides to delegate to someone else), so itd be useful knowing what his preferences on the matter are. we need to come up with a streamlined system that would make the changes easy to review, easy to evaluate and would guard against what i would deem "spam"(think bug "reports" that would have been better suited for Ask For Help)
User avatar
nnnik
Posts: 4500
Joined: 30 Sep 2013, 01:01
Location: Germany

Re: Suggestions on documentation improvements

24 Dec 2019, 06:15

Ragnar is one of the main contributors of the docs project.
Submitting a PR is only way your change will ever become a part of the docs. In addition to that you need to make a post here.
Making a post here and then making the PR seems like the best idea.
I will make a new forum section named "Suggestions on Documentation improvements" once I have a bit of feedback from the other staff members in the staff forums.
Recommends AHK Studio
guest3456
Posts: 3454
Joined: 09 Oct 2013, 10:31

Re: Suggestions on documentation improvements

24 Dec 2019, 08:55

since lexikos will be the main decider, why shouldn't all doc suggestions just be PRs? i think they should. then each "suggestion" has its own thread to discuss the viability. i've made a PR to the docs without ever posting here, and lexikos has explained his decision to reject right in the PR thread

User avatar
nnnik
Posts: 4500
Joined: 30 Sep 2013, 01:01
Location: Germany

Re: Suggestions on documentation improvements

24 Dec 2019, 10:35

lexikos removed the issues tab from the AutoHotkey repository since "github is not the place to discuss changes to AutoHotkey".
Additionally it would be impossible for some to make PRs.
Also you should ever only make a PR after you got the opinion of some other people. The forum is the place to get feedback.
Recommends AHK Studio
joefiesta
Posts: 494
Joined: 24 Jan 2016, 13:54
Location: Pa., USA

Re: Suggestions on documentation improvements

24 Dec 2019, 15:27

Wow. It is so nice to get support about my suggestion. Thank you. The doc is so important. It is very, very good, but AHK is SO very, very, very, very complicated and convoluted that the doc must be given more attention. Just look at how many ASK FOR HELP issues are resolved by pointing out the answer in the doc. The answers can be next to impossible to find (disregarding, of course, all the lazy users out there).

Return to “Suggestions on Documentation Improvements”

Who is online

Users browsing this forum: No registered users and 12 guests