The terribleness of the contemporary Delphi help experience is obviously well known. Moreover, attempts to defend it have long since degenerated into self-parody. To take one particularly egregious example of the latter, recently uttered with a straight face on the Embarcadero forums: apparently, it’s OK for the TTaskDialog component to have no documentation whatsoever incomplete documentation,* since it ‘merely’ wraps functionality provided by the Windows API. The fact that this would be a reason for not documenting 90% of the VCL did not strike our valient defender of Embarcadero ineptness as a big deal — all it went to show was how truly thankful paying customers should have been for TButton and the rest being documented back in D1!
The terribleness of the Delphi help takes many forms though, by no means limiting itself to a lack of content in certain areas. Check out this code sample for instance. Where to begin?
- In the first place, showing how to construct a new action manager at runtime so as to populate a TPopupActionMenu added at design time seems an example for one-more-example’s sake: anyone with half a brain is going to contruct an action manager at design time given all the settings to set, and a fortiori, the design-time UI for settings those settings.
- As for the actual code, the image list component is created without an owner, yet never explictly freed.
- While the temporary bitmap is freed, it is done so using Destroy directly and without try/finally protection. Picky? Not really IMO, especially given newbies are going to be reading it (though to be fair, whoever wrote the code gives strong signs of being a newbie him or herself…).
- The author does not understand the TCustomXXX naming convention in the VCL.
- The author also makes the newbie ‘mistake’ of referencing the form by its global variable within one of its own methods rather than the local Self variable. The fact that the author does this four times (and in the last, for the sake of fully qualifying an instance field) suggests he or she has not totally grasped the distinction between a global routine and a method. Naturally, this would be understandable for a beginner, what with the VCL streaming system’s war against encapsulation. But one would hope that example code put into a product’s help system isn’t going to be written by a beginner in that product, right…?
- Last but not least, why on earth is the OnGetControlClass event of the popup action menu handled? It just looks like the product of aimless playing about by a novice (‘let’s see what handling that event does…’).
To be fair, given the sheer terribleness of this particular case, I did try randomly picking out other samples in the DocWiki’s (rather extensive) list, and never found anything nearly so bad. Maybe there’s hope after all…
* As is often the case, the last-ditch defender of Borland/CodeGear/Embarcadero actually implies things to be worse than they actually are. The documentation for TTaskDialog is in reality OK, even if it doesn’t cover the particular issue the forum questioner was interested in.