Extending class documentation and live templates

Question

I am playing with code documentation and live templates and I quite don't get it.

I've read Dr.Bob's article about generating documentation and wiki articles about live templates but I have one problem with class description.

By class description I understand the IDE behaviour when I point my mouse cursor over class declaration.

For example, I have such class with it's description:

type
  {$REGION 'TMyClass'}
    /// <summary>
    /// Summary works
    /// </summary>
    /// <remarks>
    /// Remarks works
    /// </remarks>
    /// <exception cref="www.some.link">This works</exception>
    /// <list type="bullet">
    /// <item>
    /// <description>description does not work</description>
    /// </item>
    /// <item>
    /// <description>description does not work</description>
    /// </item>
    /// </list>
    /// <permission cref="www.some.link">This works</permission>
    /// <example>
    /// <code>
    /// Code example does not work
    /// </code>
    /// </example>
  {$ENDREGION}
  TMyClass = class
  private
    a, b, c: Integer;
  public
  end;

And later in the code I have such declaration:

var
  MyObject: TMyClass;

When I put mouse cursor over the class type I have such description:

Class description

As you see not every html tag was rendered by the IDE engine. I would really want to know how to render additional tags, especially tag with code example. Is it possible?

I am using Delphi 2009 Proffesional.

score 8 · Accepted Answer · answered Sep 25 '11 at 19:35

8

Only limited set of tags is supported. The best documentation about this stuff I'm aware of is the DevJET Software's Delphi Documentation Guidelines (at the end of the "Table of Contents" there is link to the PDF).

answered Sep 25 '11 at 19:35

ain

22,394
3
54
74

**I don't find that the best documentation for that stuff at all!** It is the documentation of the tags DevJet's **commercial** 3rd party tool supports. It is not the documentation of what the IDE supports. The IDE actually documents the tags the IDE supports pretty well, in the online help (and the docwiki). – Rudy Velthuis Sep 26 '11 at 14:02
Perhaps the official documentation has been improved since I last looked into that topic... at the time I looked into it the link I provided was the best (and IIRC only) documentation there were. – ain Sep 26 '11 at 15:25
Yeah, the Devjet's doc lists more tags than supported by the IDE but the documentation itself is much better than the official documentation you posted - it has examples and descriptions of the tags while the docwiki basically just has the list of tags... – ain Sep 26 '11 at 22:02
Thank you. I accept this answer because the documentation link which you gave is more helpful then the one on the wiki. Wiki does not say how to use and tags - I had no idea that they must be contained in other tags to work properly. – Wodzu Sep 27 '11 at 07:04

Rudy Velthuis · Answer 2 · 2011-09-26T14:00:16.027

3

The tags Help Insight supports are described in the online help and the Delphi docwiki. They are a subset of the tags C#'s help tags support. No other tags than the ones listed on the Embarcadero site seem to be supported (I have tried them). The only other things that work (and are required) are "<", ">" and """.

Update

There seem to be some products that allow you to use the full syntax as e.g. described in the Delphi Documentation Guidelines linked to by @ain. But that requires you to buy a commercial product like DevJet's Documentation Insight, which should not be confused with the Help Insight the IDE supports since Delphi 2006.

As you found out, and I did too, only the subset described in the Delphi docwiki is supported by the bare IDE without commercial products. There is also the documentation that is supported by the Modelling interface, but that is different again. In the normal IDE, you can only use the tags you and I already found.

edited Sep 26 '11 at 14:00

answered Sep 25 '11 at 23:11

Rudy Velthuis

28,387
5
46
94

Hi, Rudy, Actually, XMLDoc tags are just tags and dcc only extracts these tags into external xml files and doesn't care what these tags are. (Only handle the cref attribute and normalize the code reference). – Baoquan Zuo Sep 30 '11 at 04:15
P.S. Documentation Insight only makes it much easier to read and write documentation. You may still follow the guidlines above and write xmldoc tags by hand although it is really a challenge to keep xmldoc comments well-formatted. :) – Baoquan Zuo Sep 30 '11 at 04:19
@Paul: no matter what the possibilities are, out of the box, Help Insight only recognizes the tags described in the help. So you can add all the other tags in your source code, but someone else with a standard install won't be able to use them. That these tags can be enhanced by a download is irrelevant here, but thanks for the tip. – Rudy Velthuis Sep 30 '11 at 08:11
@RudyVelthuis Yes, that's it. Our mission is to broadcast the enhanced Help Insight template to benefit the community. : ) We will provide a FREE Documentation Pack which includes the customizable Help Insight template and the Guidelines in future. – Baoquan Zuo Oct 01 '11 at 13:57
@Paul: fact is that if I write documentation for my units in these units, I can't assume that someone *has* the enhanced template, so I'm restricted to what *Help Insight* offers out of the box. – Rudy Velthuis Oct 02 '11 at 09:40

Extending class documentation and live templates

2 Answers2

Update