… is available for download from Borland Code CentralTwo years ago I’ve been sitting at the C#Builder Train-The-Trainer course with other consultants and presales here in the Amsterdam office. Our master trainer Juan was covering some real basic stuff, so I thought I’d rather try to write a little application for learning purposes.
We were in the middle of discussion how potentially useful is C# XML Documentation feature to automate documentation creation. Quick search on the Internet revealed the existence of the MSDN Mag article XML Comments Let You Build Documentation Directly From Your Visual Studio .NET Source Files. Do we have something like this in C#Builder? Nope. So maybe we could display inside a web browser the XML doc file for the current project transformed to HTML with one of the XSL stylesheets selectable from the combo box? This was the beginning of my BDN article and the C#Builder XML Documentation Viewer Wizard.
Since Delphi 8 it is straightforward to write plug-ins for BDS with Delphi for .NET. In fact you can write them either with managed .NET code or unmanaged Delphi for Win32. AFAIK the later option is the only way to achieve IDE dockable forms. Nevertheless I have decided to stick with the managed code and to rewrite my C# wizard in Delphi for .NET. There are two options for GUI development with Delphi for .NET: VCL for .NET Forms and .NET FCL WinForms. I couldn’t manage to find a simple way of embedding ActiveX controls like Microsoft Web Browser on VCL for .NET forms, so I had to go for WinForms. To be honest I prefer the VCL experience over the FCL, but if you have a good reason like this to use WinForms…
One of the most difficult problems was how to display HTML in the Web Browser control from memory, without saving a resulting document and navigating to it. The hack is to typecast WebBrowser’s Document property to appropriate interface. First of all you have to make sure that Document property is not nil before you can write to it. To ensure this call Navigate(’about:blank’). After this call you can typecast to IHTMLDocument2 interface defined in Borland.mshtml namespace (do not forget to add "Borland.mshtml.dll" to project References) and then call its write method.
procedure TWinFormXmlDocViewer.DisplayHtml(s: string); var aDoc: IHTMLDocument2; objArray: array of System.&Object; begin aDoc := webBrows.Document as IHTMLDocument2; aDoc.close; // clears current doc SetLength(objArray,1); objArray := s; aDoc.write(objArray); end;
The Delphi 2005 version of the XML Documentation Viewer Wizard has received a little face-lift, and now supports exporting transformed documentation to clipboard and saving to files. There is also a new "Refresh" button and possibility to open arbitrary xml doc files. C#Builder plugin was refreshing itself, when active project was changed. The new version refreshes also after every successful compilation.
Most of the XSL stylesheets that come with the wizard are designed for C#, but there is also a simple one for Delphi, that displays just a table of namespaces in current project. Delphi for Win32 and Delphi for .NET compilers support xml documentation, however the approach here is quite different. The C# compiler generates one XML doc file for the whole project, and Delphi generates one xml doc file per each unit. Also names of tags are different, and the structure of files is different. The wizard works for every personality, as it is basically looking for a file with the same name as a current project, but with the extension changed to *.xml.