May 26, 2010

In Praise of Help Insight Support

By using a specific commenting style, not only you can enable XMLDoc, but also make Help Insight work the way it was supposed to.

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.

 





 

13 Comments

In Praise of Help Insight Support 

Excellent tip. I had no clue!

Looking forward to your next post on the tags.
Comment by K.A. on May 26, 09:30

In Praise of Help Insight Support 

Wow, I had no idea that even THIS existed! Yes, yes,
yes, this is the most useful feature in C# compared to
Delphi. The ability to document your own code so that
variables and even function parameters automatically
appear in the help insight/intellisense if you tag
comments appropriately.
Comment by Delfi Phan on May 26, 09:31

In Praise of Help Insight Support 

"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?"

There's no need to clutter the source files with
annotation comments. In theory the XMLDoc mechanism
supports gathering the documentation from an external
file. If you still have BDS 2006 installed, go to
%WINDIR%\system32, you'll find a lot of .xml files
like rtl100.xml, vcl100.xml etc. with the entire
VCL/RTL documentation in them. Help Insight should be
able to draw the information from those XML files. I
remember that it used to work in Delphi for .NET, but
I never got it to work in Delphi/Win32.

I agree that this should be implemented ASAP. I
recently did a project in Java with NetBeans, and I
hardly ever had to explicitly look up anything because
the Javadocs were available directly in the code
editor. Help Insight, if implemented properly, can be
a /huge/ boost in productivity.
Comment by Moritz Beutel [http://www.audacia-software.de/] on May 26, 13:21

In Praise of Help Insight Support 

 One of the reason might be that is what buggy, even 
unusable a couple of versions ago when introduced. 
Another could be that it tends to clutter the code.
So, more than one gave up on this feature. 

I must be one of the few to have insisted a little bit 
more. For instance:

  private type
    ///<summary> Array of the 3 fields used for a given 
Day-Log </summary>
    ///<remarks> ID#, Ref#, Day#  </remarks>
    TFieldsForLog = array[1..3] of TField;

But guess what? It's been removed from the code since.
Comment by François on May 26, 18:16

In Praise of Help Insight Support 

Marco,

  The key issue with peppering the source code with
all sorts of documentation has to do with the fact
that we'd have to translate these comments. This would
mean that all the source code would have to be
processed by translation tools, which might screw up
things like the number of lines in the file which
would make using debug dcus an exercise in
frustration. We could opt to not translate the
comments, but then large swaths of our documentation
would be in English only while other portions are
properly translated.

Allen.
Comment by Allen Bauer [http://blogs.embarcadero.com] on May 26, 19:07

In Praise of Help Insight Support 

Yes, again one of the half-baked features in Delphi
that could be really useful!

If only they supported out of the box:

1. Supported the ability to write the XMLDoc xml files
to a defined path.  Polluting the source tree with xml
files is very cumbersome.  See and vote on
http://qc.embarcadero.com/wc/qcmain.aspx?d=84911

2. Ability to generate html documentation.  See and
vote on http://qc.embarcadero.com/wc/qcmain.aspx?d=32019

Comment by Nicholas Brooks on May 26, 21:58

In Praise of Help Insight Support 

> Why third party component vendors don't add them as 
well? 

Because it doesn't work consistently and you are 
blindly stepping in the dark trying to get it to work 
on packages. Even if you have the generated XML files 
in 400 different places on your HDD.

I sent an email to Nick about it a nearly two years 
ago now which didn't end with a solution.

Might work well for units in the active project, not 
so good for other units on the system.
Comment by Jeremy North [http://www.jed-software.com] on May 26, 22:03

In Praise of Help Insight Support 

Allen, it might be worth it seriously considering NOT
to translate the help at all anymore, and leave it in
english (everywhere).

Developers use english anyways, references are in
english, and tech docs translations are more useless
than useful IME, as the translation process always
sabotages the doc one way or another (yours,
microsoft's, etc.) making them unreliable.
Comment by Eric [http://delphitools.info] on May 27, 06:16

In Praise of Help Insight Support 

Although from a non-English speaking country, I agree 
that translation efforts are useless if they don't 
start from a good documentation, and usually 
translation can introduce mistakes and bad 
interpretations. When I look for documentation (i.e. 
Microsoft, Oracle), I look for English one.
Moreover Delphi isn't translated in languages where 
it is widely used (i.e. Russian, Portoguese/Brasilian 
and Chinese). Instead of translating and adding more 
translations it would be better to concentrate 
efforts in getting far better documentation.
Many of the newest features are very poorly 
explained, and it is also very difficult to find help 
on very basic concepts, beginners have a very hard 
time getting proficient in Delphi.
It is true that it looks that many Delphi communities 
are "localizing" themselves, IMHO that's a big 
mistakes because it will just fragment and scatter 
informations.
Comment by Luigi D. Sandon on May 27, 21:00

In Praise of Help Insight Support 

Allan Bauer's light dismissal of this feature is
deeply disappointing.

I have no idea whether it is translated, but in our
German-speaking environment, everybody uses the
English version anyway.

I repeat: C# implements this extremely well, with a
good set of tags allowing popups for each parameter,
too. They appear immediately in the Intellisense
(Microsoft's name for the same thing) without
recompiling. 

And to those who say they clutter your code: there is
no obligation to use them. But as the project's
complexity grows, the namespace fills up and more
detailed parameter and function names have to be
dreamt up.

To me, Microsoft's implementation of this was an
eye-opener at how to boost productivity with
intelligently thought-out tools.

The fact I groan a bit every time I go back to a
Delphi project.
Comment by Delfi Phan on May 28, 07:49

In Praise of Help Insight Support 

 Nice tip!
I never used XmlDoc and didn't even knew how it work. 
Thanks!

p.s. It is very unpleasant for me to see, that 
Embarcadero do not use technologies they develope in 
their products. Imho, one of the biggest steps to make 
Delphi more popular is to make it more comfortable.
Comment by Aleksey Timohin [http://www.tdelphiblog.com] on May 28, 09:53

In Praise of Help Insight Support 

I try out XMLDoc in Delpi2010. The Help Insight
support works fine, but only for the first type in the
unit. Comments on a second class are written to the
xml file but ignored by HelpInsight. Bug?
Comment by hansmaad [http://www.doxapp.com] on August 30, 10:03

In Praise of Help Insight Support 

I have the very same problem on my Delphi 2010.  Any 
news on if there is a fix for this? 
Comment by Mark on September 3, 12:25


Post Your Comment

Click here for posting your feedback to this blog.

There are currently 0 pending (unapproved) messages.