Nick Hodges, Delphi Product Manager, has recently announced “Live Templates Contest”.
Live Templates were introduced in Delphi 2006. In depth explanation of Live Templates can be found on Delphi wiki. Another great reference is Nick’s camtasia presentation.
As a CodeGear employee I’m not going to participate in the contest but I thought it would be cool to create a Live Template for making it easier to add XML Documentation comments into your code. Just type in "xdoc" and when you hit enter the template should expand to:
///<summary>documentation comment</summary>
Using "summary" element in the xml doc comment enables Help Insight functionality to display the contents of your comment in the tooltip window when you move a mouse over a symbol in the code editor. The "xdoc" template is very simple and can be downloaded from code central. To install it, select File->New->Other and then in the dialog select Other Files->Code Template. Replace the default template content with the template code and save.
Added on 2007, February 1st:
For convinience below is the "xdoc" template, so you can just copy and paste it from here.
<?xml version="1.0" encoding="utf-8" ?>
<codetemplate xmlns="http://schemas.borland.com/Delphi/2005/codetemplates" version="1.0.0">
<template name="xdoc" invoke="auto">
<description>Help Insight XML Documentation comment with "summary" element</description>
<author>CodeGear</author>
<point name="comment">
<text>documentation comment</text>
<hint>XML Documentation comment goes here</hint>
</point>
<code language="Delphi" delimiter="|">
<![CDATA[///<summary>|comment|</summary>]]>
</code>
</template>
</codetemplate>
In order to increase the readability of your comments you may want to use "c" tags inside the "summary" tag. Help Insight will use a different font for these parts of documentation comments that are enclosed with "c" tags. This is useful for identifiers. If you want to see which documentation tags are recognized by Help Insight consult "HelpInsight.xsl" stylesheet located in "ObjRepos" directory.
{ 10 } Comments
For another example of Code Templates, see http://www.bobswart.nl/Weblog/Blog.aspx?RootId=5:285
I have done a few xml-comments-related templates when designing CBC. After installing CBC, there is a menu item in the Start Menu named ”Install extra templates”. Click it and a few C# templates will be added.
see http://cc.codegear.com/Item/24010
(The only problem is that these templetes are manual, not auto.)
In fact I am wondering why Delphi cannot generate basic xml comments for us. SharpDevelop has such a nice feature.
Forget to mention, keyword after /// cannot be triggered by SPACE or TAB key, you must use CTRL + J.
The templates in CBC do not have "///", so you should trigger them after typing ”///”. Because keywords after ”///” cannot be triggered by SPACE or TAB key, you must use CTRL + J.
http://blog.csdn.net/lextm/archive/2007/01/31/1499249.aspx
I blog about how to use the CBC code templates here.
Hi Mark,
> (The only problem is that these templetes are manual, not auto.)
have you tried to change "template" element attribute value from "manual" to "auto"?
The Delphi Wiki’s coverage is in depth on everything except the scripting itself, which is woefully undocumented.
Re: "Using "summary" element in the xml doc comment enables Help Insight functionality to display the contents of your comment in the tooltip window when you move a mouse over a symbol in the code editor. "… I get this to work if the symbol is in the same file, but using the symbol in another file doesn’t show the "summary" info. I’ve posted this question in the ide.general newsgroup but don’t see any leads on solving the problem. Suggestions? Want to join us in that thread, please? Thanks
Hi Dan,
As posted on the ide.general thread I’m also not getting tooltip summary comments from different units. I’m going to investigate this:-)
P.
Is there more documentation about code templates? Especially the <stript> tag seems quite interesting but I cannot find any documentation about it whatsoever.
Post a Comment