who said anything about spoonfeeding scripters? that's a very arrogant position to take on the matter at hand and rude as well.
what seems missing then in the documentation is the distinction between channel-specific and network-specific events. if by documenting this distinction it becomes clear certain event variables will or won't be defined, then you have accomplished something. Just the fact that some will or won't be defined is a hint for goodness sake! So you're an expert on the entire IRC RFC series - nice, how nice for you. But to expect every scripter at least attempting to do something useful with a script to be expert on the entire body of knowledge first is the essence of the worst kind of arrogance.
For what I have accomplished - a window of active nicks per channel that indicates how soon it has been since the last activity was noted and removes inactive nicks - $chan(N) does the job needed. $comchan($me,N) does the same, however it took quite a bit of effort and research to encounter the one (or was it only two) places in the Forum where this information could be found. $chan(N) itself never appeared in those Forum posts.
There a classes of events. There are certain things which apply and will be defined and certain things which do not apply and won't be defined. Great! Document the hell out of that, will ya?!
Who said "on DISCONNECT" needs an example? I said there's a list which gives the impression of being The Canonical List of Events which is missing an entry for DISCONNECT which is an event that can be processed. An oversight? perhaps. should the oversight or lack of entry be defended as being How It Ought to Be? doubtful. If I could add the entry myself, much as one adds to a Wiki, I would have done so already. But I cannot. I must instead use this Forum to make the case and maybe Something Will Be Done. Good move on not saying "thanks" for my good intent.
You have a closed-source scripting language here, so how the heck does one find the definitional information about the language if not in the Documentation. Oh, sure, try the Forum. Maybe it'll help - maybe it won't. I don't happen to subscribe to that notion. Rather, I subscribe to the "you the author and supporters know you can do better documentation, so do it, why don't you please?" notion.
yes, granted, I am writing this while under the full influence of testiness caused by your taking a greater than thou stance on the matter at hand. if you don't see what you did there... well... just know i've written many things in many languages and never before have I encountered this level of "surprise" when developing new code. if you choose not to respect that, it's your own fault.
as for documenting a deprecated feature: that's called "hey if you've written a script using this here feature be well and truly informed it is slated to go away. Adjust your scripts accordingly." The feature has been (perhaps cavalierly) documented informally. Alternatively, since the feature appears to have supporters, document it since it's useful and is not deprecated! You're stuck with the fact it is in fact documented at present in a feeble way. Fix -that-, why don't you?
The effort expended on this thread could have already made significant improvements to the Help File part of the product.