For many versions, Delphi has had support for XMLDoc, the production of one XML file with all symbols for each Delphi unit compiled, which you can decorate with special comments getting turned into developer information. (By the way, this is a tip part of my TIps session at Delphi Developer Days 2010).

For example, given a form class you can prefix it with the following comment (to obtain which I've defined a simple Live Template, originally covered in my Delphi 2007 Handbook):

If you now turn on XMLDoc among the compiler options, you'll get this information in an XML file like in the following snippet:

      <class name="TForm3">
        <devnotes>
          <summary>my latest very nice form, used for fun</summary>
        </devnotes>
        <ancestor name="TForm" namespace="Forms">

This can be interesting, but is quite cumbersome to use, as it requires extra tools to turn those XML files into a ready-to-use code documentation.

The key feature you directly obtain by using these special comments, however, is the availability of the "summary" information in the Help Insight pane for the given symbol:

There is no need to compile, no need to turn on the XMLDoc option, as the special comment is picked up by the parser (you need to have the source code files visible to and "browseable" by the IDE, though). Now my question is: Why don't we have Help Insight information for the symbols (classses, methods, properties, global functions) in the VCL? Why third party component vendors don't add them as well? The VCL has this kind of comments only in the code DBX units, not something you use every day.

Now I do have some hope, as Nick Hodges blogged about: "adding XMLDoc comments to the TSmiley code. Seriously. Help Insight will now provide more information that you might ever care to know."

Please, please, plase put effor in this more than in the traditional help (which badly needs an upgrade, but will be used much less regardless of its actual quality. 

PS: In another blog post (ASAP) I'll also show you how to customize Help Insight and learn about the various XML tags it supports.