however, when documentation gives little indication when variables are defined or are $null depending on which Event is being processed, then the documentation seems lacking some useful information.
The documentation can't really be expected to list every identifier that is $null for every event. That would take years and the benefit of having such information wouldn't really be worth the effort. Unless you're suggestion he only do it for some events and not others, but that would only lead to inconsistencies in the documentation.
What usually happens is that someone will try to use $chan in on QUIT/on NICK (the two most common events where people expect this identifier to work), and when it doesn't, they will either ask a friend, help channel or online forum why it's not working. Once the reason has been explained it's pretty obvious why this identifier doesn't work for those events; they are not channel-specific events, they are network specific.
You cannot use $chan(N) as an identifier to use in those events to get the shared channels between you and that nickname because $chan(N) already does something different. $comchan($nick,N) works perfectly fine. Why re-invent the wheel and break an existing identifier at the same time?
in my effort to assist improving a product I have spent money on, I offer the suggestion to note what is missing from the "on QUIT" and "on DISCONNECT" sections of the help file and request the adding of a mention of the usefulness of $chan(N) when processing those events.
Whilst Khaled could add a section to the help file that mentions this, it's not really his job to spoon feed scripters. $comchan() is documented in the help file and on QUIT/on NICK are network-specific events, not channel-specific. You can put 2 and 2 together to figure out what you need to do to get the channels shared between you and the nick triggering the event.
in addition, I note in the "Remote" section of the help file, where it appears is a list of each event and links to 'examples and tips on how to use them', the event "DISCONNECT" is not present. If a link is added in that part of the help file, it would need only lead to the same place as the "CONNECT" link since at present they are documented together on one page.
on DISCONNECT should maybe have an example, but I expect the reason it doesn't is because the syntax is exactly the same as on CONNECT. The only difference is it triggers when you disconnect rather than when you connect!
as for this "me" level, it would seem the consensus is it is not a very useful feature (checking "if $nick == $me" is a substitute and is also more descriptive script-wise). Documenting it as "deprecated and marked for removal as of version X" may be in order?
It's useful in the sense that it's quite a bit shorter than the alternative, making it easier and faster to type if you just need to write up a quick script.
Khaled doesn't usually remove features. There are deprecated features that have been there for years and years.
//window -d @test | setlayer 150 @test
/setlayer is deprecated but you can still use it to set transparency of desktop windows.
Documenting a deprecated feature seems a little silly to me.