Getting <param> data exported

Aug 1, 2007 at 7:46 PM
I'm using the "Export to Web" XML file to drive documentation for a API - this tool is a real timesaver! I am having trouble though figuring out how to access the "/// <param>" sections of the methods - is this possible in the current version?

Mike
Developer
Aug 6, 2007 at 3:48 AM
Hi Mike,

PowerToys obtains the tags of "XML Documentation Comments" through a mechanism provided by Class Designer.
That is the elements on Class Diagram have Methods or Properties exposed to user to obtain information about them, such as "<summary>" and "<remarks>" tags. Unfortunately, there is no mechanism for us to get "<param>" tags in Class Designer.

Any way, there are means to get "<param>" tags. Such as getting them directly through source code or throught some tools.

But since PowerToys is an extension of Class Designer and Distributed System Designer, maybe we had better provide usability base on these designers, so as to preserve the structure. Maybe you have aready noticed, what we provide in XML files match what in "Property Window" when an element is selected.

Thanks for using PowerToy. And We are glad to see you feel it a timesaver.

Please kindly share your opinion on this issue.
If "<param>" sections is realy useful, and widely needed, maybe we need to tell the folks work for class designer.

Thanks,


neelm wrote:
I'm using the "Export to Web" XML file to drive documentation for a API - this tool is a real timesaver! I am having trouble though figuring out how to access the "/// <param>" sections of the methods - is this possible in the current version?

Mike

Aug 6, 2007 at 1:22 PM
Thanks for the response!

The param documentation can be set in the Class Designer (though it's listed as summary) so it is part of the tool, but I understand it may not be part of the API provided with VS. I have the source, so I may look into a hack for my needs, but I agree with you on the scope of the tool.

I had looked around at several documentation tools designed to work with XML comments and I like PowerToys because it's integrated into the IDE and is simple - I just need a page of HTML documentation for a Web Service I maintain. Using the XML for PowerToys with some quick asp.net and I have everything I want - in most cases I don't really need param docs - there are a handful of methods though that I would like to add additional information to.

Mike
Aug 6, 2007 at 3:15 PM
After playing with the source, this is possible just not hooked up.

In the ExportForWebCommand.cs, WriteMember(), Line 356 I changed:

EndElement();
break;

to:

foreach (ClrParameter param in member.ClrParameters) {
WriteParameter(param);
}
EndElement();
break;


The XML generated now has <Parameter/> tags inside of the <Method/>, and the Summary attribute matched the ///<param/> documentation for that Parameter.

Mike
Developer
Aug 7, 2007 at 5:18 AM
Hi Mike,

The WriteParameter(ClrParameter param) method was designed for parameters of Delegates. I have not realized that it could also work for other intention.

I should have done more inverstigation before responsed so hurriedly.

I think attaching the <Parameter/> tags could be useful. But unlike the parameters of a delegate, the parameters of a method are not shown on the class diagram in common scenarios, while the exported xml document is for the class diagram. We will have a discuss to deside whether we should brougt parameter information to the exported xml document.

By the way, you could remove the "Position properties" of the shapes by removing the statements inside the method "WriteDiagramItem(DiagramItem item)" at line 208. So that the generated document is more neat for your document.

Thanks,
Qing
Aug 7, 2007 at 12:57 PM
I would leave in the position information - if someone was using the XML to drive their own graphical view system it would be handy. The extra info doesn't hurt in either case. The parameter export could be an option on the export for web dialog. This would help the "use case" of using the XML to drive a doc system (plus I won't have to keep track of a modified version and pass it to all the devs) ;)