I've added a link to some Format examples above.
Wow, a better documentation than AutoHotkey? I think AutoHotkey's is one of the best documentations I've seen.
I think the AutoHotkey documentation is very good, my main recommendations would be:
- the use of '[' and ']' for optional parameters can be confusing, but this can be fixed by examples with/without the optional parameters, I'm not sure if it's clearly stated somewhere that that's what the square brackets mean
- more examples, is often the best solution (I find this true of IT, maths, anything), that way if the explanations are lacking, you still find something that works, and from inspecting the examples, you can work out what's going on, also, if the language barrier is the problem, this makes explanations less useful and examples more useful
- chicken and the egg, sometimes the documentation is so bad, that people don't realise how bad it is, if they understood the topic better, they'd realise how bad that part of the documentation is, where are all the new users complaining about part of the documentation, nowhere, they already gave up on trying to read it
- objects can be hard, and the information is in many different places, I'm not sure that there is an obvious 'objects page 1', but the main solution though, to improve the objects documentation, is more examples, nothing more than that
- I write various tutorials (I have about a dozen on the way)
- I collected everything that I think the documentation should cover (or emphasise) but doesn't (currently):
jeeswg's documentation extension tutorial - AutoHotkey Community
https://autohotkey.com/boards/viewtopic.php?f=7&t=33596
- with perhaps literally one or two exceptions, everything is usually there in the documentation, although 'hidden' sometimes
- in trying to understand objects, when I first obtained a complete list of ComObjXXX and ObjXXX functions, this was the key first step, that led me to finally unravel all the issues to do with objects, but I was told by someone, something like: this is not the way to introduce objects and that it wouldn't work for anybody else
- I believe in explicitly listing all the functions somewhere, I've tried to do this myself,
list of every command/function/variable from across all versions - AutoHotkey Community
https://autohotkey.com/boards/viewtopic.php?f=7&t=27321
in AHK v2 I've, in the last one or two days, discovered accidentally that there are ListView and TreeView functions for the AHK v2 GUI, not the first time I've discovered some functions accidentally, with functions named in a way that corresponds to object methods, i.e. your can work out the pattern for yourself, but that aren't explicitly listed, similarly the ObjXXX functions were/are not listed explicitly anywhere
- it's difficult but important to put yourself in the mind of a newb, every once in a while I introduce someone to AutoHotkey