HelpInsight documentation in Delphi 2007

Question

I am using D2007 and am trying to document my source code, using the HelpInsight feature (provided since D2005). I am mainly interested in getting the HelpInsight tool-tips working. From various Web-surfing and experimentation I have found the following:

1. Using the triple slash (///) comment style works more often than the other documented comment styles. i.e.: {*! comment *} and {! comment }
2. The comments must precede the declaration that they are for. For most cases this will mean placing them in the interface section of the code. (The obvious exception is for types and functions that are not accessible from outside the current unit and are therefore declared in the implementation block.)
3. The first comment cannot be for a function. (i.e. it must be for a type - or at least it appears the parser must have seen the "type" keyword before the HelpInsight feature works)

Despite following these "rules", sometimes the Help-insight just doesn't find the comments I've written. One file does not produce the correct HelpInsight tool-tips, but if I include this file in a different dummy project, it works properly.

Does anyone have any other pointers / tricks for getting HelpInsight to work?

Answer 1

I have discovered another caveat (which in my case was what was "wrong")

It appears that the unit with the HelpInsight comments must be explicitly added to the project. It is not sufficient to simply have the unit in a path that is searched when compiling the project.

In other words, the unit must be included in the Project's .dpr / .dproj file. (Using the Project | "Add to Project" menu option)

Answer 2

Looks like you have collected most of the useful information already. Thanks!